feat(aircoding): AirCoding V2 baseline — deterministic multi-agent architecture

Forked from OpenCode v1.17.4 with multi-agent system:
- 5 agents: aircoding, scheduler, worker, architect, reviewer
- Deterministic DAG scheduling engine (coordinator_tick)
- Tool whitelists as hard enforcement
- AirCoding validation plugin
- System prompt injection for routing
- V1 requirements: C4 docs, ADR, AGENTS.md, debug-log.md
- Design documents in docs/

packages/opencode/test/cli/account.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test"
+import stripAnsi from "strip-ansi"
+
+import { defaultConsoleUrl, formatAccountLabel, formatOrgLine } from "../../src/cli/cmd/account"
+
+describe("console account display", () => {
+  test("uses console.opencode.ai as the default login URL", () => {
+    expect(defaultConsoleUrl).toBe("https://console.opencode.ai")
+  })
+
+  test("includes the account url in account labels", () => {
+    expect(stripAnsi(formatAccountLabel({ email: "one@example.com", url: "https://one.example.com" }, false))).toBe(
+      "one@example.com https://one.example.com",
+    )
+  })
+
+  test("includes the active marker in account labels", () => {
+    expect(stripAnsi(formatAccountLabel({ email: "one@example.com", url: "https://one.example.com" }, true))).toBe(
+      "one@example.com https://one.example.com (active)",
+    )
+  })
+
+  test("includes the account url in org rows", () => {
+    expect(
+      stripAnsi(
+        formatOrgLine({ email: "one@example.com", url: "https://one.example.com" }, { id: "org-1", name: "One" }, true),
+      ),
+    ).toBe("  ● One  one@example.com  https://one.example.com  org-1")
+  })
+})

packages/opencode/test/cli/acp/acp-test-client.ts

@@ -0,0 +1,97 @@
+import { expect } from "bun:test"
+import type { SessionConfigOption, SessionConfigSelectOption } from "@agentclientprotocol/sdk"
+import { Duration, Effect } from "effect"
+import type { AcpHandle } from "../../lib/cli-process"
+
+type JsonRpcRequest = {
+  readonly jsonrpc: "2.0"
+  readonly id: number
+  readonly method: string
+  readonly params?: unknown
+}
+
+type JsonRpcResponse<T = unknown> = {
+  readonly jsonrpc: "2.0"
+  readonly id: number
+  readonly result?: T
+  readonly error?: unknown
+}
+
+type JsonRpcNotification<T = unknown> = {
+  readonly jsonrpc: "2.0"
+  readonly method: string
+  readonly params?: T
+}
+
+export type AcpClient = {
+  readonly request: <T>(method: string, params?: unknown) => Effect.Effect<JsonRpcResponse<T>, unknown>
+  readonly receive: Effect.Effect<unknown>
+  readonly waitForNotification: <T>(
+    method: string,
+    predicate: (params: T) => boolean,
+    timeoutMs?: number,
+  ) => Effect.Effect<JsonRpcNotification<T>, unknown>
+}
+
+export function createAcpClient(acp: AcpHandle): AcpClient {
+  const state = { nextId: 1 }
+
+  const request = <T>(method: string, params?: unknown) =>
+    Effect.gen(function* () {
+      const id = state.nextId++
+      const message: JsonRpcRequest =
+        params === undefined ? { jsonrpc: "2.0", id, method } : { jsonrpc: "2.0", id, method, params }
+      yield* acp.send(message)
+
+      while (true) {
+        const received = yield* acp.receive.pipe(Effect.timeout(Duration.seconds(15)))
+        if (isJsonRpcResponse<T>(received) && received.id === id) return received
+      }
+    })
+
+  const waitForNotification = <T>(method: string, predicate: (params: T) => boolean, timeoutMs = 15_000) =>
+    Effect.gen(function* () {
+      while (true) {
+        const received = yield* acp.receive.pipe(Effect.timeout(Duration.millis(timeoutMs)))
+        if (!isJsonRpcNotification<T>(received)) continue
+        if (received.method === method && predicate(received.params as T)) return received
+      }
+    })
+
+  return {
+    request,
+    receive: acp.receive,
+    waitForNotification,
+  }
+}
+
+export function expectOk<T>(response: JsonRpcResponse<T>) {
+  expect(response.error).toBeUndefined()
+  expect(response.result).toBeDefined()
+  return response.result as T
+}
+
+export function selectConfigOption(options: SessionConfigOption[] | null | undefined, id: string) {
+  return options?.find(
+    (option): option is Extract<SessionConfigOption, { type: "select" }> =>
+      option.id === id && option.type === "select",
+  )
+}
+
+export function firstAlternateValue(option: Extract<SessionConfigOption, { type: "select" }>) {
+  return flattenSelectOptions(option).find((item) => item.value !== option.currentValue)?.value
+}
+
+export function flattenSelectOptions(option: Extract<SessionConfigOption, { type: "select" }>) {
+  return option.options.flatMap((item): SessionConfigSelectOption[] => ("value" in item ? [item] : item.options))
+}
+
+function isJsonRpcResponse<T>(input: unknown): input is JsonRpcResponse<T> {
+  if (!input || typeof input !== "object") return false
+  return "id" in input && "jsonrpc" in input
+}
+
+function isJsonRpcNotification<T>(input: unknown): input is JsonRpcNotification<T> {
+  if (!input || typeof input !== "object") return false
+  return "method" in input && !("id" in input) && "jsonrpc" in input
+}

packages/opencode/test/cli/acp/config-options.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect } from "bun:test"
+import type { SetSessionConfigOptionResponse } from "@agentclientprotocol/sdk"
+import { Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+import { expectOk, flattenSelectOptions, selectConfigOption } from "./acp-test-client"
+import {
+  createAcpClient,
+  expectAlternateValue,
+  expectSelectOption,
+  initialize,
+  newSession,
+  verifierConfig,
+} from "./helpers"
+
+describe("opencode acp config option subprocess", () => {
+  cliIt.live(
+    'model option is listed with category "model"',
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const model = expectSelectOption((yield* newSession(acp, home)).configOptions, "model")
+
+        expect(model.category).toBe("model")
+        expect(model.currentValue).toBe("test/test-model")
+        expect(flattenSelectOptions(model).length).toBeGreaterThanOrEqual(2)
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "model switch updates currentValue",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+        const model = expectSelectOption(session.configOptions, "model")
+        const nextModel = flattenSelectOptions(model).find((option) => option.value === "test/second-model")?.value
+        expect(nextModel).toBe("test/second-model")
+
+        const updated = expectOk(
+          yield* acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+            sessionId: session.sessionId,
+            configId: "model",
+            value: nextModel,
+          }),
+        )
+
+        expect(selectConfigOption(updated.configOptions, "model")?.currentValue).toBe(nextModel)
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    'effort option is listed with category "thought_level" when selected model supports variants',
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const effort = expectSelectOption((yield* newSession(acp, home)).configOptions, "effort")
+
+        expect(effort.category).toBe("thought_level")
+        expect(effort.currentValue).toBe("low")
+        expect(flattenSelectOptions(effort).map((option) => option.value)).toEqual(["low", "high"])
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "effort switch updates currentValue",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+        const nextEffort = expectAlternateValue(expectSelectOption(session.configOptions, "effort"))
+
+        const updated = expectOk(
+          yield* acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+            sessionId: session.sessionId,
+            configId: "effort",
+            value: nextEffort,
+          }),
+        )
+
+        expect(selectConfigOption(updated.configOptions, "effort")?.currentValue).toBe(nextEffort)
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/acp/helpers.ts

@@ -0,0 +1,96 @@
+import { expect } from "bun:test"
+import type { InitializeResponse, NewSessionResponse, SessionConfigOption } from "@agentclientprotocol/sdk"
+import { Effect } from "effect"
+import type { CliFixture } from "../../lib/cli-process"
+import { testProviderConfig } from "../../lib/test-provider"
+import {
+  createAcpClient as createJsonRpcAcpClient,
+  expectOk,
+  flattenSelectOptions,
+  selectConfigOption,
+  type AcpClient,
+} from "./acp-test-client"
+
+export function createAcpClient(input: Pick<CliFixture, "opencode">, env?: Record<string, string>) {
+  return Effect.gen(function* () {
+    return createJsonRpcAcpClient(yield* input.opencode.acp(env ? { env } : undefined))
+  })
+}
+
+export function initialize(acp: AcpClient) {
+  return Effect.gen(function* () {
+    return expectOk(
+      yield* acp.request<InitializeResponse>("initialize", {
+        protocolVersion: 1,
+        clientCapabilities: { _meta: { "terminal-auth": true } },
+        clientInfo: { name: "opencode-local-acp", version: "0.1.0" },
+      }),
+    )
+  })
+}
+
+export function newSession(acp: AcpClient, cwd: string) {
+  return Effect.gen(function* () {
+    return expectOk(yield* acp.request<NewSessionResponse>("session/new", { cwd, mcpServers: [] }))
+  })
+}
+
+export function verifierConfig(llmUrl: string, skills?: string) {
+  const config = testProviderConfig(llmUrl)
+  return {
+    ...config,
+    model: "test/test-model",
+    ...(skills ? { skills: { paths: [skills] } } : {}),
+    provider: {
+      test: {
+        ...config.provider.test,
+        models: {
+          "test-model": {
+            ...config.provider.test.models["test-model"],
+            variants: {
+              low: {},
+              high: {},
+            },
+          },
+          "second-model": {
+            ...config.provider.test.models["test-model"],
+            id: "second-model",
+            name: "Second Test Model",
+            variants: {
+              medium: {},
+              max: {},
+            },
+          },
+        },
+      },
+    },
+  }
+}
+
+export function expectErrorCode(error: unknown, code: number) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    expect(error).toEqual({ code })
+    return
+  }
+  expect(error.code).toBe(code)
+}
+
+export function expectSelectOption(options: SessionConfigOption[] | null | undefined, id: string) {
+  const option = selectConfigOption(options, id)
+  expect(option).toBeDefined()
+  return option!
+}
+
+export function expectAlternateValue(option: ReturnType<typeof expectSelectOption>) {
+  const value = flattenSelectOptions(option).find((item) => item.value !== option.currentValue)?.value
+  expect(value).toBeDefined()
+  return value!
+}
+
+export const verifierSkill = `---
+name: verifier-skill
+description: Verifier compatibility skill.
+---
+
+# Verifier Skill
+`

packages/opencode/test/cli/acp/initialize-auth.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect } from "bun:test"
+import type { AuthenticateResponse, InitializeResponse } from "@agentclientprotocol/sdk"
+import { Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+import { createAcpClient, expectErrorCode, initialize } from "./helpers"
+
+describe("opencode acp initialize/auth subprocess", () => {
+  cliIt.live(
+    "initialize responds with capabilities",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const initialized = yield* initialize(yield* createAcpClient({ opencode }))
+
+        expect(initialized.protocolVersion).toBe(1)
+        expect(initialized.agentCapabilities?.promptCapabilities?.embeddedContext).toBe(true)
+        expect(initialized.agentCapabilities?.promptCapabilities?.image).toBe(true)
+        expect(initialized.agentCapabilities?.mcpCapabilities?.http).toBe(true)
+        expect(initialized.agentCapabilities?.mcpCapabilities?.sse).toBe(true)
+        expect(initialized.agentCapabilities?.loadSession).toBe(true)
+        expect(initialized.agentCapabilities?.sessionCapabilities?.close).toEqual({})
+        expect(initialized.agentCapabilities?.sessionCapabilities?.fork).toEqual({})
+        expect(initialized.agentCapabilities?.sessionCapabilities?.list).toEqual({})
+        expect(initialized.agentCapabilities?.sessionCapabilities?.resume).toEqual({})
+        expect(initialized.agentInfo?.name).toBe("OpenCode")
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "auth negotiation is explicit and safe",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient({ opencode })
+        const initialized = yield* initialize(acp)
+
+        expect(initialized.authMethods?.[0]?.id).toBe("opencode-login")
+        expect(initialized.authMethods?.[0]?._meta?.["terminal-auth"]).toBeDefined()
+        expect(yield* acp.request<AuthenticateResponse>("authenticate", { methodId: "opencode-login" })).toMatchObject({
+          result: {},
+        })
+
+        const rejected = yield* acp.request<AuthenticateResponse>("authenticate", { methodId: "missing-auth-method" })
+        expectErrorCode(rejected.error, -32602)
+        expect(JSON.stringify(rejected.error)).not.toContain(process.env.OPENCODE_AUTH_CONTENT ?? "not-present")
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "initialize without terminal-auth metadata keeps auth command implicit",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient({ opencode })
+        const initialized = yield* acp.request<InitializeResponse>("initialize", { protocolVersion: 1 })
+
+        expect(initialized.result?.authMethods?.[0]?.id).toBe("opencode-login")
+        expect(initialized.result?.authMethods?.[0]?._meta?.["terminal-auth"]).toBeUndefined()
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/acp/lifecycle.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect } from "bun:test"
+import type {
+  CloseSessionResponse,
+  ListSessionsResponse,
+  LoadSessionResponse,
+  ResumeSessionResponse,
+} from "@agentclientprotocol/sdk"
+import { Duration, Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+import { expectOk, selectConfigOption } from "./acp-test-client"
+import { createAcpClient, initialize, newSession, verifierConfig } from "./helpers"
+
+describe("opencode acp lifecycle subprocess", () => {
+  cliIt.live(
+    "stdin EOF exits cleanly",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* opencode.acp()
+        acp.close()
+
+        const code = yield* Effect.promise(() => acp.exited).pipe(Effect.timeout(Duration.seconds(5)))
+        expect(code).toBe(0)
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "close capability and close request",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        const initialized = yield* initialize(acp)
+        expect(initialized.agentCapabilities?.sessionCapabilities?.close).toEqual({})
+
+        const session = yield* newSession(acp, home)
+        expectOk(yield* acp.request<CloseSessionResponse>("session/close", { sessionId: session.sessionId }))
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "loadSession capability and load request return session config options",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        const initialized = yield* initialize(acp)
+        expect(initialized.agentCapabilities?.loadSession).toBe(true)
+        const session = yield* newSession(acp, home)
+        const loaded = expectOk(
+          yield* acp.request<LoadSessionResponse>("session/load", {
+            cwd: home,
+            sessionId: session.sessionId,
+            mcpServers: [],
+          }),
+        )
+
+        expect(selectConfigOption(loaded.configOptions, "model")?.category).toBe("model")
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "list request includes a live ACP-created session",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+        const listed = expectOk(yield* acp.request<ListSessionsResponse>("session/list", { cwd: home }))
+
+        expect(listed.sessions.some((item) => item.sessionId === session.sessionId)).toBe(true)
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "resume capability advertisement",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const initialized = yield* initialize(yield* createAcpClient({ opencode }))
+
+        expect(initialized.agentCapabilities?.sessionCapabilities?.resume).toEqual({})
+      }),
+    60_000,
+  )
+
+  cliIt.live(
+    "resume request returns session config options",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+        const resumed = expectOk(
+          yield* acp.request<ResumeSessionResponse>("session/resume", {
+            cwd: home,
+            sessionId: session.sessionId,
+            mcpServers: [],
+          }),
+        )
+
+        expect(selectConfigOption(resumed.configOptions, "model")?.category).toBe("model")
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/acp/prompt-content.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect } from "bun:test"
+import type { PromptResponse } from "@agentclientprotocol/sdk"
+import { Effect } from "effect"
+import { writeFile } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import { cliIt } from "../../lib/cli-process"
+import { expectOk } from "./acp-test-client"
+import { createAcpClient, initialize, newSession, verifierConfig } from "./helpers"
+
+const tinyPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII="
+
+describe("opencode acp prompt content subprocess", () => {
+  cliIt.live(
+    "accepts embedded text resource image and file resource link prompt content",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* Effect.promise(() => writeFile(path.join(home, "README.md"), "# ACP content smoke\n"))
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(promptContentConfig(llm.url)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+
+        yield* llm.text("embedded resource accepted")
+        expectOk(
+          yield* acp.request<PromptResponse>("session/prompt", {
+            sessionId: session.sessionId,
+            prompt: [
+              { type: "text", text: "Use this embedded resource." },
+              {
+                type: "resource",
+                resource: { uri: "file:///context.txt", mimeType: "text/plain", text: "embedded context" },
+              },
+            ],
+          }),
+        )
+
+        yield* llm.text("image accepted")
+        expectOk(
+          yield* acp.request<PromptResponse>("session/prompt", {
+            sessionId: session.sessionId,
+            prompt: [
+              { type: "text", text: "Use this image." },
+              {
+                type: "image",
+                mimeType: "image/png",
+                data: tinyPng,
+              },
+            ],
+          }),
+        )
+
+        yield* llm.text("file link accepted")
+        const linked = expectOk(
+          yield* acp.request<PromptResponse>("session/prompt", {
+            sessionId: session.sessionId,
+            prompt: [
+              { type: "text", text: "Use this linked file." },
+              {
+                type: "resource_link",
+                uri: pathToFileURL(path.join(home, "README.md")).href,
+                name: "README.md",
+                mimeType: "text/markdown",
+              },
+            ],
+          }),
+        )
+
+        expect(linked.stopReason).toBe("end_turn")
+      }),
+    60_000,
+  )
+})
+
+function promptContentConfig(llmUrl: string) {
+  const config = verifierConfig(llmUrl)
+  return {
+    ...config,
+    provider: {
+      test: {
+        ...config.provider.test,
+        models: Object.fromEntries(
+          Object.entries(config.provider.test.models).map(([id, model]) => [
+            id,
+            {
+              ...model,
+              attachment: true,
+              reasoning: true,
+            },
+          ]),
+        ),
+      },
+    },
+  }
+}

packages/opencode/test/cli/acp/skills.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect } from "bun:test"
+import type { SessionNotification } from "@agentclientprotocol/sdk"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import path from "node:path"
+import { cliIt } from "../../lib/cli-process"
+import { createAcpClient, initialize, newSession, verifierConfig, verifierSkill } from "./helpers"
+
+describe("opencode acp skills subprocess", () => {
+  cliIt.live(
+    "skill slash command appears through available_commands_update",
+    ({ home, llm, opencode }) =>
+      Effect.gen(function* () {
+        const skills = path.join(home, "skills")
+        yield* Effect.promise(() => mkdir(path.join(skills, "verifier-skill"), { recursive: true }))
+        yield* Effect.promise(() => Bun.write(path.join(skills, "verifier-skill", "SKILL.md"), verifierSkill))
+        const acp = yield* createAcpClient(
+          { opencode },
+          { OPENCODE_CONFIG_CONTENT: JSON.stringify(verifierConfig(llm.url, skills)) },
+        )
+        yield* initialize(acp)
+        const session = yield* newSession(acp, home)
+
+        const update = yield* acp.waitForNotification<SessionNotification>(
+          "session/update",
+          (params) =>
+            params.sessionId === session.sessionId &&
+            params.update.sessionUpdate === "available_commands_update" &&
+            params.update.availableCommands.some(
+              (command) => command.name === "verifier-skill" && command.description.length > 0,
+            ),
+        )
+
+        expect(update.params?.sessionId).toBe(session.sessionId)
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/cmd/tui/attention.test.ts

@@ -0,0 +1,484 @@
+import { describe, expect, test } from "bun:test"
+import type { AudioPlayOptions, AudioSound } from "@opentui/core"
+import { createTuiAttention } from "@opencode-ai/tui/attention"
+import type { TuiConfig } from "@opencode-ai/tui/config"
+
+type FocusEvent = "focus" | "blur"
+
+type AttentionConfig = Pick<TuiConfig.Resolved, "attention">
+
+class FakeRenderer {
+  isDestroyed = false
+  notificationResult = true
+  notificationThrows = false
+  notifications: { message: string; title: string | undefined }[] = []
+  listeners: Record<FocusEvent, Set<() => void>> = {
+    focus: new Set(),
+    blur: new Set(),
+  }
+
+  on(event: FocusEvent, listener: () => void) {
+    this.listeners[event].add(listener)
+    return this
+  }
+
+  off(event: FocusEvent, listener: () => void) {
+    this.listeners[event].delete(listener)
+    return this
+  }
+
+  emit(event: FocusEvent) {
+    for (const listener of this.listeners[event]) listener()
+  }
+
+  listenerCount(event: FocusEvent) {
+    return this.listeners[event].size
+  }
+
+  triggerNotification(message: string, title?: string) {
+    if (this.notificationThrows) throw new Error("notification failed")
+    this.notifications.push({ message, title })
+    return this.notificationResult
+  }
+}
+
+class FakeAudioEngine {
+  loadResult: AudioSound | null = 1
+  playResult: number | null = 1
+  loadCalls = 0
+  playCalls = 0
+  volumes: (number | undefined)[] = []
+  loadPaths: string[] = []
+  rejectLoad = false
+  rejectPaths = new Set<string>()
+
+  async loadSoundFile(path: string) {
+    this.loadCalls += 1
+    this.loadPaths.push(path)
+    if (this.rejectLoad || this.rejectPaths.has(path)) throw new Error("decode failed")
+    return this.loadResult
+  }
+
+  play(_sound: AudioSound, options?: AudioPlayOptions) {
+    this.playCalls += 1
+    this.volumes.push(options?.volume)
+    return this.playResult
+  }
+}
+
+class FakeKV {
+  store: Record<string, unknown> = {}
+
+  get ready() {
+    return true
+  }
+
+  get<Value = unknown>(key: string, fallback?: Value) {
+    return (this.store[key] ?? fallback) as Value
+  }
+
+  set(key: string, value: unknown) {
+    this.store[key] = value
+  }
+}
+
+function config(attention: Partial<AttentionConfig["attention"]> = {}): AttentionConfig {
+  return {
+    attention: {
+      enabled: true,
+      notifications: true,
+      sound: true,
+      volume: 0.4,
+      sound_pack: "opencode.default",
+      sounds: {},
+      ...attention,
+    },
+  }
+}
+
+describe("createTuiAttention", () => {
+  test("defaults to sound always and notification blurred", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "hello" })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("supports blurred-only requests", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "unknown", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focus_unknown",
+    })
+    renderer.emit("focus")
+    expect(await attention.notify({ message: "focused", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focused",
+    })
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", sound: { when: "blurred" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("supports focused-only requests", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+
+    expect(await attention.notify({ message: "unknown", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focus_unknown",
+    })
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "blurred",
+    })
+    renderer.emit("focus")
+    expect(await attention.notify({ message: "focused", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "focused" }])
+  })
+
+  test("notification can deliver while focused when requested", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(await attention.notify({ message: "hello", notification: { when: "always" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.playCalls).toBe(1)
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello" }])
+  })
+
+  test("notifies while blurred", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ title: "opencode", message: "hello", sound: false })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello" }])
+  })
+
+  test("when requested, blurred-only calls do not notify or play sound while focused", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(await attention.notify({ message: "hello", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focused",
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.loadCalls).toBe(0)
+  })
+
+  test("can play sound always while notification is blurred-only", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(
+      await attention.notify({
+        message: "hello",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+
+    renderer.emit("blur")
+    expect(
+      await attention.notify({
+        message: "hello again",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello again" }])
+  })
+
+  test("can disable notification per call while still playing sound", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "hello", notification: false })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("skips empty messages and disabled attention", async () => {
+    const empty = new FakeRenderer()
+    empty.emit("blur")
+    const disabled = new FakeRenderer()
+    disabled.emit("blur")
+
+    expect(await createTuiAttention({ renderer: empty, config: config() }).notify({ message: " \n " })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "empty_message",
+    })
+    expect(
+      await createTuiAttention({ renderer: disabled, config: config({ enabled: false }) }).notify({ message: "hello" }),
+    ).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "attention_disabled",
+    })
+  })
+
+  test("respects notification and sound config independently", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config({ notifications: false }), audio })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+
+    const soundDisabledRenderer = new FakeRenderer()
+    const soundDisabledAudio = new FakeAudioEngine()
+    const soundDisabled = createTuiAttention({
+      renderer: soundDisabledRenderer,
+      config: config({ sound: false }),
+      audio: soundDisabledAudio,
+    })
+    soundDisabledRenderer.emit("blur")
+
+    expect(await soundDisabled.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(soundDisabledAudio.loadCalls).toBe(0)
+  })
+
+  test("loads audio lazily only for eligible sound requests", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    await attention.notify({ message: "unknown", sound: { when: "blurred" } })
+    expect(audio.loadCalls).toBe(0)
+
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", sound: { volume: 2 } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadCalls).toBe(1)
+    expect(audio.volumes).toEqual([1])
+  })
+
+  test("handles unavailable playback and delegates sound loading", async () => {
+    const unavailableRenderer = new FakeRenderer()
+    const unavailableAudio = new FakeAudioEngine()
+    unavailableAudio.playResult = null
+    const unavailable = createTuiAttention({ renderer: unavailableRenderer, config: config(), audio: unavailableAudio })
+    unavailableRenderer.emit("blur")
+
+    expect(await unavailable.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(unavailableAudio.loadCalls).toBe(1)
+    expect(unavailableAudio.playCalls).toBe(1)
+
+    const repeatedRenderer = new FakeRenderer()
+    const repeatedAudio = new FakeAudioEngine()
+    const repeated = createTuiAttention({ renderer: repeatedRenderer, config: config(), audio: repeatedAudio })
+    repeatedRenderer.emit("blur")
+
+    await repeated.notify({ message: "one", sound: true })
+    await repeated.notify({ message: "two", sound: true })
+    expect(repeatedAudio.loadCalls).toBe(2)
+    expect(repeatedAudio.playCalls).toBe(2)
+  })
+
+  test("plays named sounds from the active sound pack", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+
+    const dispose = attention.soundboard.registerPack({
+      id: "acme.soft",
+      name: "Soft Alerts",
+      sounds: {
+        question: "/tmp/question.mp3",
+      },
+    })
+
+    expect(attention.soundboard.activate("acme.soft")).toBe(true)
+    expect(attention.soundboard.current()).toBe("acme.soft")
+    expect(attention.soundboard.list()).toContainEqual({
+      id: "acme.soft",
+      name: "Soft Alerts",
+      active: true,
+      builtin: false,
+    })
+
+    expect(await attention.notify({ message: "question", sound: { name: "question" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadPaths).toEqual(["/tmp/question.mp3"])
+
+    dispose()
+    expect(attention.soundboard.current()).toBe("opencode.default")
+  })
+
+  test("uses config sound overrides before active pack sounds and falls back on load failure", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    audio.rejectPaths.add("/tmp/bad-question.mp3")
+    const attention = createTuiAttention({
+      renderer,
+      config: config({ sounds: { question: "/tmp/bad-question.mp3" } }),
+      audio,
+    })
+    renderer.emit("blur")
+
+    attention.soundboard.registerPack({
+      id: "acme.soft",
+      sounds: {
+        question: "/tmp/good-question.mp3",
+      },
+    })
+    attention.soundboard.activate("acme.soft")
+
+    expect(await attention.notify({ message: "question", sound: { name: "question" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadPaths).toEqual(["/tmp/bad-question.mp3", "/tmp/good-question.mp3"])
+  })
+
+  test("persists activated sound pack in KV", () => {
+    const kv = new FakeKV()
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), kv })
+
+    attention.soundboard.registerPack({ id: "acme.soft", sounds: { done: "/tmp/done.mp3" } })
+
+    expect(attention.soundboard.activate("missing", { persist: true })).toBe(false)
+    expect(kv.store.attention_sound_pack).toBeUndefined()
+    expect(attention.soundboard.activate("acme.soft", { persist: true })).toBe(true)
+    expect(kv.store.attention_sound_pack).toBe("acme.soft")
+
+    const next = createTuiAttention({ renderer: new FakeRenderer(), config: config(), kv })
+    next.soundboard.registerPack({ id: "acme.soft", sounds: { done: "/tmp/done.mp3" } })
+    expect(next.soundboard.current()).toBe("acme.soft")
+  })
+
+  test("does not throw for notification or sound failures", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    renderer.notificationThrows = true
+    audio.rejectLoad = true
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+    })
+  })
+
+  test("strips unsafe notification text", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+    renderer.emit("blur")
+
+    await attention.notify({
+      title: "\u001b[31m danger\n title\u0007",
+      message: "\u001b[32m hello\n world\u0000",
+    })
+
+    expect(renderer.notifications).toEqual([{ title: "danger title", message: "hello world" }])
+  })
+
+  test("disposes renderer listeners", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+    await attention.notify({ message: "hello", sound: true })
+
+    expect(renderer.listenerCount("focus")).toBe(1)
+    expect(renderer.listenerCount("blur")).toBe(1)
+
+    attention.dispose()
+    renderer.isDestroyed = true
+
+    expect(renderer.listenerCount("focus")).toBe(0)
+    expect(renderer.listenerCount("blur")).toBe(0)
+    expect(audio.loadCalls).toBe(1)
+    expect(await attention.notify({ message: "hello" })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "renderer_destroyed",
+    })
+  })
+})

packages/opencode/test/cli/effect-cmd-instance-als.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, expect } from "bun:test"
+import { FSUtil } from "@opencode-ai/core/fs-util"
+import { Effect } from "effect"
+import { fileURLToPath } from "url"
+import { InstanceRef } from "../../src/effect/instance-ref"
+import { disposeAllInstances, TestInstance } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(FSUtil.defaultLayer)
+
+afterEach(async () => {
+  await disposeAllInstances()
+})
+
+it.live("effect-cmd.ts does not restore legacy instance ALS", () =>
+  Effect.gen(function* () {
+    const fs = yield* FSUtil.Service
+    const source = yield* fs.readFileString(fileURLToPath(new URL("../../src/cli/effect-cmd.ts", import.meta.url)))
+    expect(source).not.toContain("restore(ctx")
+  }),
+)
+
+it.instance(
+  "InstanceRef remains the handler context across Effect promise awaits",
+  () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const ctx = yield* InstanceRef
+      if (!ctx) throw new Error("InstanceRef not provided")
+
+      const directory = yield* Effect.promise(async () => {
+        await Promise.resolve()
+        return ctx.directory
+      })
+
+      expect(directory).toBe(test.directory)
+    }),
+  { git: true },
+)

packages/opencode/test/cli/error.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test"
+import { AccountTransportError } from "../../src/account/schema"
+import { FormatError } from "../../src/cli/error"
+import { UI } from "../../src/cli/ui"
+
+describe("cli.error", () => {
+  test("formats legacy and tagged config errors the same way", () => {
+    const cases = [
+      {
+        tag: "ConfigJsonError",
+        data: { path: "/tmp/opencode.jsonc", message: "Unexpected token" },
+        expected: "Config file at /tmp/opencode.jsonc is not valid JSON(C): Unexpected token",
+      },
+      {
+        tag: "ConfigDirectoryTypoError",
+        data: { path: "/tmp/opencode.jsonc", dir: ".opencode", suggestion: "opencode" },
+        expected:
+          'Directory ".opencode" in /tmp/opencode.jsonc is not valid. Rename the directory to "opencode" or remove it. This is a common typo.',
+      },
+      {
+        tag: "ConfigFrontmatterError",
+        data: { path: "/tmp/AGENTS.md", message: "failed frontmatter" },
+        expected: "failed frontmatter",
+      },
+      {
+        tag: "ConfigInvalidError",
+        data: {
+          path: "/tmp/opencode.jsonc",
+          message: "schema mismatch",
+          issues: [{ message: "Expected string", path: ["provider", "id"] }],
+        },
+        expected: "Configuration is invalid at /tmp/opencode.jsonc: schema mismatch\n↳ Expected string provider.id",
+      },
+    ]
+
+    for (const item of cases) {
+      expect(FormatError({ name: item.tag, data: item.data })).toBe(item.expected)
+      expect(FormatError({ _tag: item.tag, ...item.data })).toBe(item.expected)
+    }
+  })
+
+  test("preserves multiline JSONC diagnostics for tagged config errors", () => {
+    const data = {
+      path: "/tmp/opencode.jsonc",
+      message:
+        '\n--- JSONC Input ---\n{\n  "model": \n}\n--- Errors ---\nValueExpected at line 3, column 1\n   Line 3: }\n          ^\n--- End ---',
+    }
+    const expected = `Config file at ${data.path} is not valid JSON(C): ${data.message}`
+
+    expect(FormatError({ name: "ConfigJsonError", data })).toBe(expected)
+    expect(FormatError({ _tag: "ConfigJsonError", ...data })).toBe(expected)
+  })
+
+  test("formats account transport errors clearly", () => {
+    const error = new AccountTransportError({
+      method: "POST",
+      url: "https://console.opencode.ai/auth/device/code",
+    })
+
+    const formatted = FormatError(error)
+
+    expect(formatted).toContain("Could not reach POST https://console.opencode.ai/auth/device/code.")
+    expect(formatted).toContain("This failed before the server returned an HTTP response.")
+    expect(formatted).toContain("Check your network, proxy, or VPN configuration and try again.")
+  })
+
+  test("formats legacy and tagged provider model errors the same way", () => {
+    const data = {
+      providerID: "anthropic",
+      modelID: "claude-sonet-4",
+      suggestions: ["claude-sonnet-4"],
+    }
+    const expected = [
+      "Model not found: anthropic/claude-sonet-4",
+      "Did you mean: claude-sonnet-4",
+      "Try: `opencode models` to list available models",
+      "Or check your config (opencode.json) provider/model names",
+    ].join("\n")
+
+    expect(FormatError({ name: "ProviderModelNotFoundError", data })).toBe(expected)
+    expect(FormatError({ _tag: "ProviderModelNotFoundError", ...data })).toBe(expected)
+  })
+
+  test("formats legacy and tagged provider init errors the same way", () => {
+    const data = { providerID: "anthropic" }
+    const expected = 'Failed to initialize provider "anthropic". Check credentials and configuration.'
+
+    expect(FormatError({ name: "ProviderInitError", data })).toBe(expected)
+    expect(FormatError({ _tag: "ProviderInitError", ...data })).toBe(expected)
+  })
+
+  test("formats cancelled UI errors as empty output", () => {
+    expect(FormatError(new UI.CancelledError())).toBe("")
+  })
+})

packages/opencode/test/cli/github-action.test.ts

@@ -0,0 +1,199 @@
+import { test, expect, describe } from "bun:test"
+import { SessionV1 } from "@opencode-ai/core/v1/session"
+import { extractResponseText, formatPromptTooLargeError } from "../../src/cli/cmd/github"
+import type { MessageV2 } from "../../src/session/message-v2"
+import { SessionID, MessageID, PartID } from "../../src/session/schema"
+
+// Helper to create minimal valid parts
+function createTextPart(text: string): SessionV1.Part {
+  return {
+    id: PartID.ascending(),
+    sessionID: SessionID.make("ses_test"),
+    messageID: MessageID.make("msg_test"),
+    type: "text" as const,
+    text,
+  }
+}
+
+function createReasoningPart(text: string): SessionV1.Part {
+  return {
+    id: PartID.ascending(),
+    sessionID: SessionID.make("ses_test"),
+    messageID: MessageID.make("msg_test"),
+    type: "reasoning" as const,
+    text,
+    time: { start: 0 },
+  }
+}
+
+function createToolPart(tool: string, title: string, status: "completed" | "running" = "completed"): SessionV1.Part {
+  if (status === "completed") {
+    return {
+      id: PartID.ascending(),
+      sessionID: SessionID.make("ses_test"),
+      messageID: MessageID.make("msg_test"),
+      type: "tool" as const,
+      callID: "c1",
+      tool,
+      state: {
+        status: "completed",
+        input: {},
+        output: "",
+        title,
+        metadata: {},
+        time: { start: 0, end: 1 },
+      },
+    }
+  }
+  return {
+    id: PartID.ascending(),
+    sessionID: SessionID.make("ses_test"),
+    messageID: MessageID.make("msg_test"),
+    type: "tool" as const,
+    callID: "c1",
+    tool,
+    state: {
+      status: "running",
+      input: {},
+      time: { start: 0 },
+    },
+  }
+}
+
+function createStepStartPart(): SessionV1.Part {
+  return {
+    id: PartID.ascending(),
+    sessionID: SessionID.make("ses_test"),
+    messageID: MessageID.make("msg_test"),
+    type: "step-start" as const,
+  }
+}
+
+function createStepFinishPart(): SessionV1.Part {
+  return {
+    id: PartID.ascending(),
+    sessionID: SessionID.make("ses_test"),
+    messageID: MessageID.make("msg_test"),
+    type: "step-finish" as const,
+    reason: "done",
+    cost: 0,
+    tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+  }
+}
+
+describe("extractResponseText", () => {
+  test("returns text from text part", () => {
+    const parts = [createTextPart("Hello world")]
+    expect(extractResponseText(parts)).toBe("Hello world")
+  })
+
+  test("returns last text part when multiple exist", () => {
+    const parts = [createTextPart("First"), createTextPart("Last")]
+    expect(extractResponseText(parts)).toBe("Last")
+  })
+
+  test("returns text even when tool parts follow", () => {
+    const parts = [createTextPart("I'll help with that."), createToolPart("todowrite", "3 todos")]
+    expect(extractResponseText(parts)).toBe("I'll help with that.")
+  })
+
+  test("returns null for reasoning-only response (signals summary needed)", () => {
+    const parts = [createReasoningPart("Let me think about this...")]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns null for tool-only response (signals summary needed)", () => {
+    // This is the exact scenario from the bug report - todowrite with no text
+    const parts = [createToolPart("todowrite", "8 todos")]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns null for multiple completed tools", () => {
+    const parts = [
+      createToolPart("read", "src/file.ts"),
+      createToolPart("edit", "src/file.ts"),
+      createToolPart("bash", "bun test"),
+    ]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns null for running tool parts (signals summary needed)", () => {
+    const parts = [createToolPart("bash", "", "running")]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("throws on empty array", () => {
+    expect(() => extractResponseText([])).toThrow("no parts returned")
+  })
+
+  test("returns null for step-start only", () => {
+    const parts = [createStepStartPart()]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns null for step-finish only", () => {
+    const parts = [createStepFinishPart()]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns null for step-start and step-finish", () => {
+    const parts = [createStepStartPart(), createStepFinishPart()]
+    expect(extractResponseText(parts)).toBeNull()
+  })
+
+  test("returns text from multi-step response", () => {
+    const parts = [
+      createStepStartPart(),
+      createToolPart("read", "src/file.ts"),
+      createTextPart("Done"),
+      createStepFinishPart(),
+    ]
+    expect(extractResponseText(parts)).toBe("Done")
+  })
+
+  test("prefers text over reasoning when both present", () => {
+    const parts = [createReasoningPart("Internal thinking..."), createTextPart("Final answer")]
+    expect(extractResponseText(parts)).toBe("Final answer")
+  })
+
+  test("prefers text over tools when both present", () => {
+    const parts = [createToolPart("read", "src/file.ts"), createTextPart("Here's what I found")]
+    expect(extractResponseText(parts)).toBe("Here's what I found")
+  })
+})
+
+describe("formatPromptTooLargeError", () => {
+  test("formats error without files", () => {
+    const result = formatPromptTooLargeError([])
+    expect(result).toBe("PROMPT_TOO_LARGE: The prompt exceeds the model's context limit.")
+  })
+
+  test("formats error with files (base64 content)", () => {
+    // Base64 is ~33% larger than original, so we multiply by 0.75 to get original size
+    // 400 KB base64 = 300 KB original, 200 KB base64 = 150 KB original
+    const files = [
+      { filename: "screenshot.png", content: "a".repeat(400 * 1024) },
+      { filename: "diagram.png", content: "b".repeat(200 * 1024) },
+    ]
+    const result = formatPromptTooLargeError(files)
+
+    expect(result).toStartWith("PROMPT_TOO_LARGE: The prompt exceeds the model's context limit.")
+    expect(result).toInclude("Files in prompt:")
+    expect(result).toInclude("screenshot.png (300 KB)")
+    expect(result).toInclude("diagram.png (150 KB)")
+  })
+
+  test("lists all files when multiple present", () => {
+    // Base64 sizes: 4KB -> 3KB, 8KB -> 6KB, 12KB -> 9KB
+    const files = [
+      { filename: "img1.png", content: "x".repeat(4 * 1024) },
+      { filename: "img2.jpg", content: "y".repeat(8 * 1024) },
+      { filename: "img3.gif", content: "z".repeat(12 * 1024) },
+    ]
+    const result = formatPromptTooLargeError(files)
+
+    expect(result).toInclude("img1.png (3 KB)")
+    expect(result).toInclude("img2.jpg (6 KB)")
+    expect(result).toInclude("img3.gif (9 KB)")
+  })
+})

packages/opencode/test/cli/github-remote.test.ts

@@ -0,0 +1,90 @@
+import { test, expect } from "bun:test"
+import { parseGitHubRemote } from "../../src/cli/cmd/github"
+
+test("parses https URL with .git suffix", () => {
+  expect(parseGitHubRemote("https://github.com/sst/opencode.git")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses https URL without .git suffix", () => {
+  expect(parseGitHubRemote("https://github.com/sst/opencode")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses git@ URL with .git suffix", () => {
+  expect(parseGitHubRemote("git@github.com:sst/opencode.git")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses git@ URL without .git suffix", () => {
+  expect(parseGitHubRemote("git@github.com:sst/opencode")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses ssh:// URL with .git suffix", () => {
+  expect(parseGitHubRemote("ssh://git@github.com/sst/opencode.git")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses ssh:// URL without .git suffix", () => {
+  expect(parseGitHubRemote("ssh://git@github.com/sst/opencode")).toEqual({ owner: "sst", repo: "opencode" })
+})
+
+test("parses git protocol URLs from package metadata", () => {
+  expect(parseGitHubRemote("git://github.com/facebook/react.git")).toEqual({ owner: "facebook", repo: "react" })
+  expect(parseGitHubRemote("git+https://github.com/facebook/react.git")).toEqual({ owner: "facebook", repo: "react" })
+  expect(parseGitHubRemote("git+ssh://git@github.com/facebook/react.git")).toEqual({ owner: "facebook", repo: "react" })
+})
+
+test("parses npm-style github shorthand", () => {
+  expect(parseGitHubRemote("github:facebook/react")).toBeNull()
+})
+
+test("parses http URL", () => {
+  expect(parseGitHubRemote("http://github.com/owner/repo")).toEqual({ owner: "owner", repo: "repo" })
+})
+
+test("parses URL with hyphenated owner and repo names", () => {
+  expect(parseGitHubRemote("https://github.com/my-org/my-repo.git")).toEqual({ owner: "my-org", repo: "my-repo" })
+})
+
+test("parses URL with underscores in names", () => {
+  expect(parseGitHubRemote("git@github.com:my_org/my_repo.git")).toEqual({ owner: "my_org", repo: "my_repo" })
+})
+
+test("parses URL with numbers in names", () => {
+  expect(parseGitHubRemote("https://github.com/org123/repo456")).toEqual({ owner: "org123", repo: "repo456" })
+})
+
+test("parses repos with dots in the name", () => {
+  expect(parseGitHubRemote("https://github.com/socketio/socket.io.git")).toEqual({
+    owner: "socketio",
+    repo: "socket.io",
+  })
+  expect(parseGitHubRemote("https://github.com/vuejs/vue.js")).toEqual({
+    owner: "vuejs",
+    repo: "vue.js",
+  })
+  expect(parseGitHubRemote("git@github.com:mrdoob/three.js.git")).toEqual({
+    owner: "mrdoob",
+    repo: "three.js",
+  })
+  expect(parseGitHubRemote("https://github.com/jashkenas/backbone.git")).toEqual({
+    owner: "jashkenas",
+    repo: "backbone",
+  })
+})
+
+test("returns null for non-github URLs", () => {
+  expect(parseGitHubRemote("https://gitlab.com/owner/repo.git")).toBeNull()
+  expect(parseGitHubRemote("git@gitlab.com:owner/repo.git")).toBeNull()
+  expect(parseGitHubRemote("https://bitbucket.org/owner/repo")).toBeNull()
+})
+
+test("returns null for invalid URLs", () => {
+  expect(parseGitHubRemote("not-a-url")).toBeNull()
+  expect(parseGitHubRemote("")).toBeNull()
+  expect(parseGitHubRemote("github.com")).toBeNull()
+  expect(parseGitHubRemote("https://github.com/")).toBeNull()
+  expect(parseGitHubRemote("https://github.com/owner")).toBeNull()
+})
+
+test("returns null for URLs with extra path segments", () => {
+  expect(parseGitHubRemote("https://github.com/owner/repo/tree/main")).toBeNull()
+  expect(parseGitHubRemote("https://github.com/owner/repo/blob/main/file.ts")).toBeNull()
+})

packages/opencode/test/cli/help/__snapshots__/help-snapshots.test.ts.snap

@@ -0,0 +1,631 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode acp --help 1`] = `
+"opencode acp
+
+start ACP (Agent Client Protocol) server
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]
+      --cwd          working directory [string] [default: "<HOME>"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp --help 1`] = `
+"opencode mcp
+
+manage MCP (Model Context Protocol) servers
+
+Commands:
+  opencode mcp add [name]     add an MCP server
+  opencode mcp list           list MCP servers and their status                        [aliases: ls]
+  opencode mcp auth [name]    authenticate with an OAuth-enabled MCP server
+  opencode mcp logout [name]  remove OAuth credentials for an MCP server
+  opencode mcp debug <name>   debug OAuth connection for an MCP server
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode attach --help 1`] = `
+"opencode attach <url>
+
+attach to a running opencode server
+
+Positionals:
+  url  http://localhost:4096                                                     [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --dir         directory to run in                                                     [string]
+  -c, --continue    continue the last session                                              [boolean]
+  -s, --session     session id to continue                                                  [string]
+      --fork        fork the session when continuing (use with --continue or --session)    [boolean]
+  -p, --password    basic auth password (defaults to OPENCODE_SERVER_PASSWORD)              [string]
+  -u, --username    basic auth username (defaults to OPENCODE_SERVER_USERNAME or 'opencode')[string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode run --help 1`] = `
+"opencode run [message..]
+
+run opencode with a message
+
+Positionals:
+  message  message to send                                                     [array] [default: []]
+
+Options:
+  -h, --help                          show help                                            [boolean]
+  -v, --version                       show version number                                  [boolean]
+      --print-logs                    print logs to stderr                                 [boolean]
+      --log-level                     log level [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure                          run without external plugins                         [boolean]
+      --command                       the command to run, use message for args              [string]
+  -c, --continue                      continue the last session                            [boolean]
+  -s, --session                       session id to continue                                [string]
+      --fork                          fork the session before continuing (requires --continue or
+                                      --session)                                           [boolean]
+      --share                         share the session                                    [boolean]
+  -m, --model                         model to use in the format of provider/model          [string]
+      --agent                         agent to use                                          [string]
+      --format                        format: default (formatted) or json (raw JSON events)
+                                          [string] [choices: "default", "json"] [default: "default"]
+  -f, --file                          file(s) to attach to message                           [array]
+      --title                         title for the session (uses truncated prompt if no value
+                                      provided)                                             [string]
+      --attach                        attach to a running opencode server (e.g.,
+                                      http://localhost:4096)                                [string]
+  -p, --password                      basic auth password (defaults to OPENCODE_SERVER_PASSWORD)
+                                                                                            [string]
+  -u, --username                      basic auth username (defaults to OPENCODE_SERVER_USERNAME or
+                                      'opencode')                                           [string]
+      --dir                           directory to run in, path on remote server if attaching
+                                                                                            [string]
+      --port                          port for the local server (defaults to random port if no value
+                                      provided)                                             [number]
+      --variant                       model variant (provider-specific reasoning effort, e.g., high,
+                                      max, minimal)                                         [string]
+      --thinking                      show thinking blocks                                 [boolean]
+      --replay                        replay interactive session history on resume and after resize
+                                      (use --no-replay to disable)         [boolean] [default: true]
+      --replay-limit                  cap visible interactive replay to the newest N messages
+                                                                                            [number]
+  -i, --interactive                   run in direct interactive split-footer mode
+                                                                          [boolean] [default: false]
+      --dangerously-skip-permissions  auto-approve permissions that are not explicitly denied
+                                      (dangerous!)                        [boolean] [default: false]
+      --demo                          enable direct interactive demo slash commands; pass one as the
+                                      message to run it immediately       [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode debug --help 1`] = `
+"opencode debug
+
+debugging and troubleshooting tools
+
+Commands:
+  opencode debug config        show resolved configuration
+  opencode debug lsp           LSP debugging utilities
+  opencode debug rg            ripgrep debugging utilities
+  opencode debug file          file system debugging utilities
+  opencode debug scrap         list all known projects
+  opencode debug skill         list all available skills
+  opencode debug snapshot      snapshot debugging utilities
+  opencode debug startup       print startup timing
+  opencode debug agent <name>  show agent configuration details
+  opencode debug v2            debug v2 catalog and built-in plugins
+  opencode debug info          show debug information
+  opencode debug paths         show global paths (data, config, cache, state)
+  opencode debug wait          wait indefinitely (for debugging)
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers --help 1`] = `
+"opencode providers
+
+manage AI providers and credentials
+
+Commands:
+  opencode providers list               list providers and credentials                 [aliases: ls]
+  opencode providers login [url]        log in to a provider
+  opencode providers logout [provider]  log out from a configured provider
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent --help 1`] = `
+"opencode agent
+
+manage agents
+
+Commands:
+  opencode agent create  create a new agent
+  opencode agent list    list all available agents
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode upgrade --help 1`] = `
+"opencode upgrade [target]
+
+upgrade opencode to the latest or a specific version
+
+Positionals:
+  target  version to upgrade to, for ex '0.1.48' or 'v0.1.48'                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -m, --method      installation method to use
+                          [string] [choices: "curl", "npm", "pnpm", "bun", "brew", "choco", "scoop"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode uninstall --help 1`] = `
+"opencode uninstall
+
+uninstall opencode and remove all related files
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+  -c, --keep-config  keep configuration files                             [boolean] [default: false]
+  -d, --keep-data    keep session data and snapshots                      [boolean] [default: false]
+      --dry-run      show what would be removed without removing          [boolean] [default: false]
+  -f, --force        skip confirmation prompts                            [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode serve --help 1`] = `
+"opencode serve
+
+starts a headless opencode server
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode web --help 1`] = `
+"opencode web
+
+start opencode server and open web interface
+
+Options:
+  -h, --help         show help                                                             [boolean]
+  -v, --version      show version number                                                   [boolean]
+      --print-logs   print logs to stderr                                                  [boolean]
+      --log-level    log level                  [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure         run without external plugins                                          [boolean]
+      --port         port to listen on                                         [number] [default: 0]
+      --hostname     hostname to listen on                           [string] [default: "127.0.0.1"]
+      --mdns         enable mDNS service discovery (defaults hostname to 0.0.0.0)
+                                                                          [boolean] [default: false]
+      --mdns-domain  custom domain name for mDNS service (default: opencode.local)
+                                                                [string] [default: "opencode.local"]
+      --cors         additional domains to allow for CORS                      [array] [default: []]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode models --help 1`] = `
+"opencode models [provider]
+
+list all available models
+
+Positionals:
+  provider  provider ID to filter models by                                                 [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --verbose     use more verbose model output (includes metadata like costs)           [boolean]
+      --refresh     refresh the models cache from models.dev                               [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode stats --help 1`] = `
+"opencode stats
+
+show token usage and cost statistics
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --days        show stats for the last N days (default: all time)                      [number]
+      --tools       number of tools to show (default: all)                                  [number]
+      --models      show model statistics (default: hidden). Pass a number to show top N, otherwise
+                    shows all
+      --project     filter by project (default: all projects, empty string: current project)[string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode export --help 1`] = `
+"opencode export [sessionID]
+
+export session data as JSON
+
+Positionals:
+  sessionID  session id to export                                                           [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --sanitize    redact sensitive transcript and file data                              [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode import --help 1`] = `
+"opencode import <file>
+
+import session data from JSON file or URL
+
+Positionals:
+  file  path to JSON file or share URL                                           [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github --help 1`] = `
+"opencode github
+
+manage GitHub agent
+
+Commands:
+  opencode github install  install the GitHub agent
+  opencode github run      run the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode pr --help 1`] = `
+"opencode pr <number>
+
+fetch and checkout a GitHub PR branch, then run opencode
+
+Positionals:
+  number  PR number to checkout                                                  [number] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session --help 1`] = `
+"opencode session
+
+manage sessions
+
+Commands:
+  opencode session list                list sessions
+  opencode session delete <sessionID>  delete a session
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode plugin --help 1`] = `
+"opencode plugin <module>
+
+install plugin and update config
+
+Positionals:
+  module  npm module name                                                        [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -g, --global      install in global config                              [boolean] [default: false]
+  -f, --force       replace existing plugin version                       [boolean] [default: false]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode db --help 1`] = `
+"opencode db
+
+database tools
+
+Commands:
+  opencode db [query]     open an interactive sqlite3 shell or run a query                 [default]
+  opencode db path        print the database path
+
+Positionals:
+  query  SQL query to execute                                                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --format      Output format                 [string] [choices: "json", "tsv"] [default: "tsv"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp list --help 1`] = `
+"opencode mcp list
+
+list MCP servers and their status
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp add --help 1`] = `
+"opencode mcp add [name]
+
+add an MCP server
+
+Positionals:
+  name  name of the MCP server                                                              [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --url         URL for a remote MCP server                                             [string]
+      --env         environment variable for a local MCP server (KEY=VALUE)                  [array]
+      --header      HTTP header for a remote MCP server (KEY=VALUE)                          [array]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp auth --help 1`] = `
+"opencode mcp auth [name]
+
+authenticate with an OAuth-enabled MCP server
+
+Commands:
+  opencode mcp auth list  list OAuth-capable MCP servers and their auth status         [aliases: ls]
+
+Positionals:
+  name  name of the MCP server                                                              [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode mcp logout --help 1`] = `
+"opencode mcp logout [name]
+
+remove OAuth credentials for an MCP server
+
+Positionals:
+  name  name of the MCP server                                                              [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers list --help 1`] = `
+"opencode providers list
+
+list providers and credentials
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers login --help 1`] = `
+"opencode providers login [url]
+
+log in to a provider
+
+Positionals:
+  url  opencode auth provider                                                               [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -p, --provider    provider id or name to log in to (skips provider selection)             [string]
+  -m, --method      login method label (skips method selection)                             [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode providers logout --help 1`] = `
+"opencode providers logout [provider]
+
+log out from a configured provider
+
+Positionals:
+  provider  provider id or name to log out from                                             [string]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent create --help 1`] = `
+"opencode agent create
+
+create a new agent
+
+Options:
+  -h, --help                  show help                                                    [boolean]
+  -v, --version               show version number                                          [boolean]
+      --print-logs            print logs to stderr                                         [boolean]
+      --log-level             log level         [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure                  run without external plugins                                 [boolean]
+      --path                  directory path to generate the agent file                     [string]
+      --description           what the agent should do                                      [string]
+      --mode                  agent mode            [string] [choices: "all", "primary", "subagent"]
+      --permissions, --tools  comma-separated list of permissions to allow (default: all).
+                              Available: "bash, read, edit, glob, grep, webfetch, task, todowrite,
+                              websearch, lsp, skill"                                        [string]
+  -m, --model                 model to use in the format of provider/model                  [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode agent list --help 1`] = `
+"opencode agent list
+
+list all available agents
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session list --help 1`] = `
+"opencode session list
+
+list sessions
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+  -n, --max-count   limit to N most recent sessions                                         [number]
+      --format      output format             [string] [choices: "table", "json"] [default: "table"]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode session delete --help 1`] = `
+"opencode session delete <sessionID>
+
+delete a session
+
+Positionals:
+  sessionID  session ID to delete                                                [string] [required]
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github install --help 1`] = `
+"opencode github install
+
+install the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode github run --help 1`] = `
+"opencode github run
+
+run the GitHub agent
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]
+      --event       GitHub mock event to run the agent for                                  [string]
+      --token       GitHub personal access token (github_pat_********)                      [string]"
+`;
+
+exports[`opencode CLI help-text snapshots every documented command emits stable help text: opencode db path --help 1`] = `
+"opencode db path
+
+print the database path
+
+Options:
+  -h, --help        show help                                                              [boolean]
+  -v, --version     show version number                                                    [boolean]
+      --print-logs  print logs to stderr                                                   [boolean]
+      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
+      --pure        run without external plugins                                           [boolean]"
+`;

packages/opencode/test/cli/help/help-snapshots.test.ts

@@ -0,0 +1,137 @@
+// Help-text snapshots for every CLI command + key subcommand. Catches
+// accidental flag removals, renames, and reordering in a single sweep —
+// any change to the user-visible CLI surface shows up here as a diff.
+//
+// This is the broad coverage layer that makes the future Effect CLI
+// migration (yargs → effect-smol/cli) safe to attempt: if a refactor
+// preserves the surface, the snapshots stay green; if it doesn't, the
+// diff tells you exactly which command(s) changed.
+//
+// Snapshots are taken at COLUMNS=120 so wrapping is stable across
+// terminal sizes. The default opencode tui command is excluded —
+// `opencode --help` includes an ASCII banner that pulls in the install
+// version (changes per release), so we'd snapshot a moving target.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { EOL } from "os"
+import { cliIt } from "../../lib/cli-process"
+import { normalizeForSnapshot, PATH_SEP } from "../../lib/snapshot"
+
+// Composes `normalizeForSnapshot` (CRLF + tmpdir) with two help-specific
+// rules:
+//
+//   1. The harness's `oc-cli-XXX` subdir under TMPDIR collapses to `<HOME>`.
+//      `PATH_SEP` matches `/` and `\\` so the rule works on POSIX + Windows.
+//
+//   2. yargs wraps the `[string] [default: "..."]` clause based on the
+//      pre-normalized default's character length, so different random home
+//      path widths produce different leading-whitespace counts (or even
+//      line-wraps onto a fresh line on Windows). `\s+` matches both forms.
+function normalize(text: string): string {
+  return normalizeForSnapshot(text, {
+    pathReplacements: [
+      // Mixed-case [A-Za-z0-9] because node's mkdtemp suffix is mixed-case
+      // (the harness now uses FileSystem.makeTempDirectoryScoped under the
+      // hood). A `[a-z0-9]+` regex would leave uppercase chars trailing.
+      [new RegExp(`<TMPDIR>${PATH_SEP}oc-cli-[A-Za-z0-9]+`, "g"), "<HOME>"],
+      [/\s+\[string\] \[default: "<HOME>"\]/g, ' [string] [default: "<HOME>"]'],
+    ],
+  })
+}
+
+// Top-level commands. Order matches what `opencode --help` prints today;
+// keep it in that order so the snapshot file reads as a table of contents.
+// `completion` is intentionally excluded — it's a yargs built-in that emits
+// top-level help on `--help` and exits 1; not a real opencode command.
+const TOP_LEVEL = [
+  "acp",
+  "mcp",
+  "attach",
+  "run",
+  "debug",
+  "providers", // aliased to `auth`
+  "agent",
+  "upgrade",
+  "uninstall",
+  "serve",
+  "web",
+  "models",
+  "stats",
+  "export",
+  "import",
+  "github",
+  "pr",
+  "session",
+  "plugin",
+  "db",
+] as const
+
+// Subcommands worth pinning. Not exhaustive — the goal is one snapshot per
+// distinct argv shape, not every leaf. Add new entries when a subcommand
+// gains user-visible flags that we want to lock in.
+const SUBCOMMANDS = [
+  ["mcp", "list"],
+  ["mcp", "add"],
+  ["mcp", "auth"],
+  ["mcp", "logout"],
+  ["providers", "list"],
+  ["providers", "login"],
+  ["providers", "logout"],
+  ["agent", "create"],
+  ["agent", "list"],
+  ["session", "list"],
+  ["session", "delete"],
+  ["github", "install"],
+  ["github", "run"],
+  ["db", "path"],
+] as const
+
+// Fixed wrap width so a developer's terminal doesn't affect snapshots.
+// yargs honors COLUMNS; CI runners typically default to 80 which produces
+// different wraps from a 200-col local terminal.
+const SNAPSHOT_ENV = { COLUMNS: "120" }
+
+describe("opencode CLI help-text snapshots", () => {
+  // Single test, parallel spawns. Each command's help fires under
+  // `concurrency: 8` — wall-clock stays under ~10s even for ~35 commands,
+  // versus ~1 minute if we serialized.
+  cliIt.live(
+    "every documented command emits stable help text",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const topLevel = yield* opencode.spawn(["--help"], { env: SNAPSHOT_ENV })
+        expect(topLevel.exitCode).toBe(0)
+        expect(topLevel.stderr.endsWith(EOL)).toBe(true)
+
+        const argvs: Array<readonly string[]> = [...TOP_LEVEL.map((c) => [c] as const), ...SUBCOMMANDS]
+
+        // Spawn in parallel, then assert in argv order so snapshot output is
+        // deterministic and per-command failures don't abort the rest of
+        // the sweep. `Effect.partition` is the canonical "run all, separate
+        // failures from successes" primitive — no mutable accumulator needed.
+        const [failures, results] = yield* Effect.partition(
+          argvs,
+          (argv) =>
+            Effect.gen(function* () {
+              const result = yield* opencode.spawn([...argv, "--help"], { env: SNAPSHOT_ENV })
+              if (result.exitCode !== 0) {
+                return yield* Effect.fail(`opencode ${argv.join(" ")}: exit ${result.exitCode}`)
+              }
+              return { argv, result }
+            }),
+          { concurrency: 8 },
+        )
+
+        for (const { argv, result } of results) {
+          // yargs writes --help to stderr, not stdout. Snapshotting stderr
+          // means our test catches the help body; stdout for these commands
+          // is expected to be empty.
+          expect(normalize(result.stderr)).toMatchSnapshot(`opencode ${argv.join(" ")} --help`)
+        }
+        if (failures.length > 0) {
+          throw new Error(`Help text failed for:\n  ${failures.join("\n  ")}`)
+        }
+      }),
+    180_000,
+  )
+})

packages/opencode/test/cli/import.test.ts

@@ -0,0 +1,54 @@
+import { test, expect } from "bun:test"
+import {
+  parseShareUrl,
+  shouldAttachShareAuthHeaders,
+  transformShareData,
+  type ShareData,
+} from "../../src/cli/cmd/import"
+
+// parseShareUrl tests
+test("parses valid share URLs", () => {
+  expect(parseShareUrl("https://opncd.ai/share/Jsj3hNIW")).toBe("Jsj3hNIW")
+  expect(parseShareUrl("https://custom.example.com/share/abc123")).toBe("abc123")
+  expect(parseShareUrl("http://localhost:3000/share/test_id-123")).toBe("test_id-123")
+})
+
+test("rejects invalid URLs", () => {
+  expect(parseShareUrl("https://opncd.ai/s/Jsj3hNIW")).toBeNull() // legacy format
+  expect(parseShareUrl("https://opncd.ai/share/")).toBeNull()
+  expect(parseShareUrl("https://opncd.ai/share/id/extra")).toBeNull()
+  expect(parseShareUrl("not-a-url")).toBeNull()
+})
+
+test("only attaches share auth headers for same-origin URLs", () => {
+  expect(shouldAttachShareAuthHeaders("https://control.example.com/share/abc", "https://control.example.com")).toBe(
+    true,
+  )
+  expect(shouldAttachShareAuthHeaders("https://other.example.com/share/abc", "https://control.example.com")).toBe(false)
+  expect(shouldAttachShareAuthHeaders("https://control.example.com:443/share/abc", "https://control.example.com")).toBe(
+    true,
+  )
+  expect(shouldAttachShareAuthHeaders("not-a-url", "https://control.example.com")).toBe(false)
+})
+
+// transformShareData tests
+test("transforms share data to storage format", () => {
+  const data: ShareData[] = [
+    { type: "session", data: { id: "sess-1", title: "Test" } as any },
+    { type: "message", data: { id: "msg-1", sessionID: "sess-1" } as any },
+    { type: "part", data: { id: "part-1", messageID: "msg-1" } as any },
+    { type: "part", data: { id: "part-2", messageID: "msg-1" } as any },
+  ]
+
+  const result = transformShareData(data)!
+
+  expect(result.info.id).toBe("sess-1")
+  expect(result.messages).toHaveLength(1)
+  expect(result.messages[0].parts).toHaveLength(2)
+})
+
+test("returns null for invalid share data", () => {
+  expect(transformShareData([])).toBeNull()
+  expect(transformShareData([{ type: "message", data: {} as any }])).toBeNull()
+  expect(transformShareData([{ type: "session", data: { id: "s" } as any }])).toBeNull() // no messages
+})

packages/opencode/test/cli/mcp-add.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import path from "path"
+import { cliIt } from "../lib/cli-process"
+
+describe("opencode mcp add (non-interactive subprocess)", () => {
+  cliIt.concurrent(
+    "adds a remote server with HTTP headers",
+    ({ home, opencode }) =>
+      Effect.gen(function* () {
+        const result = yield* opencode.spawn([
+          "mcp",
+          "add",
+          "github",
+          "--url",
+          "https://example.com/mcp",
+          "--header",
+          "Authorization=Bearer {env:GITHUB_TOKEN}",
+          "--header",
+          "X-Option=one=two",
+        ])
+        opencode.expectExit(result, 0)
+
+        const config = yield* Effect.promise(() =>
+          Bun.file(path.join(home, ".config", "opencode", "opencode.json")).json(),
+        )
+        expect(config.mcp.github).toEqual({
+          type: "remote",
+          url: "https://example.com/mcp",
+          headers: {
+            Authorization: "Bearer {env:GITHUB_TOKEN}",
+            "X-Option": "one=two",
+          },
+        })
+      }),
+    60_000,
+  )
+
+  cliIt.concurrent(
+    "adds a local server while preserving argv and environment values",
+    ({ home, opencode }) =>
+      Effect.gen(function* () {
+        const result = yield* opencode.spawn([
+          "mcp",
+          "add",
+          "local",
+          "--env",
+          "API_KEY=secret",
+          "--env",
+          "VALUE=one=two",
+          "--",
+          "npx",
+          "-y",
+          "@example/server",
+          "--label",
+          "two words",
+        ])
+        opencode.expectExit(result, 0)
+
+        const config = yield* Effect.promise(() =>
+          Bun.file(path.join(home, ".config", "opencode", "opencode.json")).json(),
+        )
+        expect(config.mcp.local).toEqual({
+          type: "local",
+          command: ["npx", "-y", "@example/server", "--label", "two words"],
+          environment: {
+            API_KEY: "secret",
+            VALUE: "one=two",
+          },
+        })
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/plugin-auth-picker.test.ts

@@ -0,0 +1,120 @@
+import { test, expect, describe } from "bun:test"
+import { resolvePluginProviders } from "../../src/cli/cmd/providers"
+import type { Hooks } from "@opencode-ai/plugin"
+
+function hookWithAuth(provider: string): Hooks {
+  return {
+    auth: {
+      provider,
+      methods: [],
+    },
+  }
+}
+
+function hookWithoutAuth(): Hooks {
+  return {}
+}
+
+describe("resolvePluginProviders", () => {
+  test("returns plugin providers not in models.dev", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([{ id: "portkey", name: "portkey" }])
+  })
+
+  test("skips providers already in models.dev", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("anthropic")],
+      existingProviders: { anthropic: {} },
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([])
+  })
+
+  test("deduplicates across plugins", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey"), hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([{ id: "portkey", name: "portkey" }])
+  })
+
+  test("respects disabled_providers", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(["portkey"]),
+      providerNames: {},
+    })
+    expect(result).toEqual([])
+  })
+
+  test("respects enabled_providers when provider is absent", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      enabled: new Set(["anthropic"]),
+      providerNames: {},
+    })
+    expect(result).toEqual([])
+  })
+
+  test("includes provider when in enabled set", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      enabled: new Set(["portkey"]),
+      providerNames: {},
+    })
+    expect(result).toEqual([{ id: "portkey", name: "portkey" }])
+  })
+
+  test("resolves name from providerNames", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: { portkey: "Portkey AI" },
+    })
+    expect(result).toEqual([{ id: "portkey", name: "Portkey AI" }])
+  })
+
+  test("falls back to id when no name configured", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithAuth("portkey")],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([{ id: "portkey", name: "portkey" }])
+  })
+
+  test("skips hooks without auth", () => {
+    const result = resolvePluginProviders({
+      hooks: [hookWithoutAuth(), hookWithAuth("portkey"), hookWithoutAuth()],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([{ id: "portkey", name: "portkey" }])
+  })
+
+  test("returns empty for no hooks", () => {
+    const result = resolvePluginProviders({
+      hooks: [],
+      existingProviders: {},
+      disabled: new Set(),
+      providerNames: {},
+    })
+    expect(result).toEqual([])
+  })
+})

packages/opencode/test/cli/run/entry.body.test.ts

@@ -0,0 +1,536 @@
+import { describe, expect, test } from "bun:test"
+import type { ToolPart } from "@opencode-ai/sdk/v2"
+import { entryBody, entryCanStream, entryDone } from "@/cli/cmd/run/entry.body"
+import type { StreamCommit, ToolSnapshot } from "@/cli/cmd/run/types"
+
+function commit(input: Partial<StreamCommit> & Pick<StreamCommit, "kind" | "text" | "phase" | "source">): StreamCommit {
+  return input
+}
+
+function toolPart(tool: string, state: ToolPart["state"], id = `${tool}-1`, messageID = `msg-${tool}`): ToolPart {
+  return {
+    id,
+    sessionID: "session-1",
+    messageID,
+    type: "tool",
+    callID: `call-${id}`,
+    tool,
+    state,
+  } as ToolPart
+}
+
+function toolCommit(input: {
+  tool: string
+  state: ToolPart["state"]
+  phase?: StreamCommit["phase"]
+  toolState?: StreamCommit["toolState"]
+  text?: string
+  id?: string
+  messageID?: string
+}) {
+  return commit({
+    kind: "tool",
+    text: input.text ?? "",
+    phase: input.phase ?? "final",
+    source: "tool",
+    tool: input.tool,
+    toolState: input.toolState ?? "completed",
+    part: toolPart(input.tool, input.state, input.id, input.messageID),
+  })
+}
+
+function structured(next: StreamCommit) {
+  const body = entryBody(next)
+  expect(body.type).toBe("structured")
+  if (body.type !== "structured") {
+    throw new Error("expected structured body")
+  }
+
+  return body.snapshot
+}
+
+describe("run entry body", () => {
+  test("renders assistant, reasoning, and user entries in their display formats", () => {
+    expect(
+      entryBody(
+        commit({
+          kind: "assistant",
+          text: "# Title\n\nHello **world**",
+          phase: "progress",
+          source: "assistant",
+          partID: "part-1",
+        }),
+      ),
+    ).toEqual({
+      type: "markdown",
+      content: "# Title\n\nHello **world**",
+    })
+
+    const reasoning = entryBody(
+      commit({
+        kind: "reasoning",
+        text: "Thinking: plan next steps",
+        phase: "progress",
+        source: "reasoning",
+        partID: "reason-1",
+      }),
+    )
+    expect(reasoning).toEqual({
+      type: "code",
+      filetype: "markdown",
+      content: "_Thinking:_ plan next steps",
+    })
+    expect(
+      entryCanStream(
+        commit({
+          kind: "reasoning",
+          text: "Thinking: plan next steps",
+          phase: "progress",
+          source: "reasoning",
+        }),
+        reasoning,
+      ),
+    ).toBe(true)
+
+    expect(
+      entryBody(
+        commit({
+          kind: "user",
+          text: "Inspect footer tabs",
+          phase: "start",
+          source: "system",
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "› Inspect footer tabs",
+    })
+  })
+
+  for (const item of [
+    {
+      name: "keeps completed write tool finals structured",
+      commit: toolCommit({
+        tool: "write",
+        state: {
+          status: "completed",
+          input: {
+            filePath: "src/a.ts",
+            content: "const x = 1\n",
+          },
+          output: "",
+          title: "",
+          metadata: {},
+          time: { start: 1, end: 2 },
+        },
+      }),
+      snapshot: {
+        kind: "code",
+        title: "# Wrote src/a.ts",
+        content: "const x = 1\n",
+        file: "src/a.ts",
+      },
+    },
+    {
+      name: "keeps completed edit tool finals structured",
+      commit: toolCommit({
+        tool: "edit",
+        state: {
+          status: "completed",
+          input: {
+            filePath: "src/a.ts",
+          },
+          output: "",
+          title: "",
+          metadata: {
+            diff: "@@ -1 +1 @@\n-old\n+new\n",
+          },
+          time: { start: 1, end: 2 },
+        },
+      }),
+      snapshot: {
+        kind: "diff",
+        items: [
+          {
+            title: "# Edited src/a.ts",
+            diff: "@@ -1 +1 @@\n-old\n+new\n",
+            file: "src/a.ts",
+          },
+        ],
+      },
+    },
+    {
+      name: "keeps completed apply_patch tool finals structured",
+      commit: toolCommit({
+        tool: "apply_patch",
+        state: {
+          status: "completed",
+          input: {},
+          output: "",
+          title: "",
+          metadata: {
+            files: [
+              {
+                type: "update",
+                filePath: "src/a.ts",
+                relativePath: "src/a.ts",
+                patch: "@@ -1 +1 @@\n-old\n+new\n",
+              },
+            ],
+          },
+          time: { start: 1, end: 2 },
+        },
+      }),
+      snapshot: {
+        kind: "diff",
+        items: [
+          {
+            title: "# Patched src/a.ts",
+            diff: "@@ -1 +1 @@\n-old\n+new\n",
+            file: "src/a.ts",
+            deletions: 0,
+          },
+        ],
+      },
+    },
+  ] satisfies Array<{ name: string; commit: StreamCommit; snapshot: ToolSnapshot }>) {
+    test(item.name, () => {
+      expect(structured(item.commit)).toEqual(item.snapshot)
+    })
+  }
+
+  test("keeps running task tool state out of scrollback", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "task",
+          phase: "start",
+          toolState: "running",
+          text: "running inspect reducer",
+          state: {
+            status: "running",
+            input: {
+              description: "Inspect reducer",
+              subagent_type: "explore",
+            },
+            time: { start: 1 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "none",
+    })
+  })
+
+  test("promotes task results to markdown and falls back to structured task summaries", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "task",
+          state: {
+            status: "completed",
+            input: {
+              description: "Inspect reducer",
+              subagent_type: "explore",
+            },
+            title: "",
+            output: [
+              '<task id="child-1" state="completed">',
+              "<task_result>",
+              "# Findings\n\n- Footer stays live",
+              "</task_result>",
+              "</task>",
+            ].join("\n"),
+            metadata: {
+              sessionId: "child-1",
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "markdown",
+      content: "# Findings\n\n- Footer stays live",
+    })
+
+    expect(
+      structured(
+        toolCommit({
+          tool: "task",
+          state: {
+            status: "completed",
+            input: {
+              description: "Inspect reducer",
+              subagent_type: "explore",
+            },
+            title: "",
+            output: ['<task id="child-1" state="completed">', "<task_result>", "", "</task_result>", "</task>"].join(
+              "\n",
+            ),
+            metadata: {
+              sessionId: "child-1",
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      kind: "task",
+      title: "# Explore Task",
+      rows: ["Inspect reducer"],
+      tail: "",
+    })
+  })
+
+  test("streams tool progress text and treats completed progress as done", () => {
+    const body = entryBody(
+      commit({
+        kind: "tool",
+        text: "partial output",
+        phase: "progress",
+        source: "tool",
+        tool: "bash",
+        partID: "tool-2",
+      }),
+    )
+
+    expect(body).toEqual({
+      type: "text",
+      content: "partial output",
+    })
+    expect(
+      entryCanStream(
+        commit({
+          kind: "tool",
+          text: "partial output",
+          phase: "progress",
+          source: "tool",
+          tool: "bash",
+        }),
+        body,
+      ),
+    ).toBe(true)
+    expect(
+      entryDone(
+        commit({
+          kind: "tool",
+          text: "output",
+          phase: "progress",
+          source: "tool",
+          tool: "bash",
+          toolState: "completed",
+        }),
+      ),
+    ).toBe(true)
+  })
+
+  test("formats completed bash output with a blank line after the command and no trailing blank row", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "bash",
+          phase: "progress",
+          toolState: "completed",
+          text: ["/tmp/demo", "git status", "On branch demo", "nothing to commit, working tree clean", ""].join("\n"),
+          state: {
+            status: "completed",
+            input: {
+              command: "git status",
+              workdir: "/tmp/demo",
+            },
+            output: ["/tmp/demo", "git status", "On branch demo", "nothing to commit, working tree clean", ""].join(
+              "\n",
+            ),
+            title: "git status",
+            metadata: {
+              exitCode: 0,
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "\nOn branch demo\nnothing to commit, working tree clean",
+    })
+  })
+
+  test("renders command-only bash starts without the shell header", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "bash",
+          phase: "start",
+          toolState: "running",
+          text: "running shell",
+          state: {
+            status: "running",
+            input: {
+              command: "ls",
+            },
+            time: { start: 1 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "$ ls",
+    })
+  })
+
+  test("renders direct shell commits without a synthetic shell header", () => {
+    expect(
+      entryBody(
+        commit({
+          kind: "tool",
+          text: "running shell",
+          phase: "start",
+          source: "tool",
+          tool: "bash",
+          partID: "shell:call-1",
+          toolState: "running",
+          shell: {
+            callID: "call-1",
+            command: "pwd",
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "$ pwd",
+    })
+
+    expect(
+      entryBody(
+        commit({
+          kind: "tool",
+          text: "/tmp/demo\n",
+          phase: "progress",
+          source: "tool",
+          tool: "bash",
+          partID: "shell:call-1",
+          toolState: "completed",
+          shell: {
+            callID: "call-1",
+            command: "pwd",
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "\n/tmp/demo",
+    })
+  })
+
+  test("falls back to patch summary when apply_patch has no visible diff items", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "apply_patch",
+          state: {
+            status: "completed",
+            input: {
+              patchText: "*** Begin Patch\n*** End Patch",
+            },
+            output: "",
+            title: "",
+            metadata: {
+              files: [
+                {
+                  type: "update",
+                  filePath: "src/a.ts",
+                  relativePath: "src/a.ts",
+                  diff: "@@ -1 +1 @@\n-old\n+new\n",
+                },
+              ],
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "~ Patched src/a.ts",
+    })
+  })
+
+  test("suppresses redundant patched rows when apply_patch also created a file", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "apply_patch",
+          state: {
+            status: "completed",
+            input: {
+              patchText: "*** Begin Patch\n*** End Patch",
+            },
+            output: "",
+            title: "",
+            metadata: {
+              files: [
+                {
+                  type: "update",
+                  filePath: "src/a.ts",
+                  relativePath: "src/a.ts",
+                  diff: "@@ -1 +1 @@\n-old\n+new\n",
+                },
+                {
+                  type: "add",
+                  filePath: "README-demo.md",
+                  relativePath: "README-demo.md",
+                },
+              ],
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "+ Created README-demo.md",
+    })
+  })
+
+  test("renders glob failures as the raw error under the existing header", () => {
+    expect(
+      entryBody(
+        toolCommit({
+          tool: "glob",
+          phase: "final",
+          toolState: "error",
+          state: {
+            status: "error",
+            input: {
+              pattern: "**/*tool*",
+              path: "/tmp/demo/run",
+            },
+            error: "No such file or directory: '/tmp/demo/run'",
+            metadata: {},
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "No such file or directory: '/tmp/demo/run'",
+    })
+  })
+
+  test("renders interrupted assistant finals as text", () => {
+    expect(
+      entryBody(
+        commit({
+          kind: "assistant",
+          text: "",
+          phase: "final",
+          source: "assistant",
+          interrupted: true,
+          partID: "part-1",
+        }),
+      ),
+    ).toEqual({
+      type: "text",
+      content: "assistant interrupted",
+    })
+  })
+})

packages/opencode/test/cli/run/footer.menu.test.ts

@@ -0,0 +1,43 @@
+import { expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { FOOTER_MENU_ROWS, createFooterMenuState } from "@/cli/cmd/run/footer.menu"
+
+function mount(count: number, limit = FOOTER_MENU_ROWS) {
+  let dispose!: () => void
+  let menu!: ReturnType<typeof createFooterMenuState>
+
+  createRoot((nextDispose) => {
+    dispose = nextDispose
+    menu = createFooterMenuState({ count: () => count, limit })
+    return null
+  })
+
+  return { menu, dispose }
+}
+
+test("footer menu scrolls before the selected row hits the bottom edge", () => {
+  const state = mount(20)
+
+  try {
+    Array.from({ length: 6 }).forEach(() => state.menu.move(1))
+
+    expect(state.menu.selected()).toBe(6)
+    expect(state.menu.offset()).toBe(1)
+  } finally {
+    state.dispose()
+  }
+})
+
+test("footer menu scrolls before the selected row hits the top edge", () => {
+  const state = mount(20)
+
+  try {
+    Array.from({ length: 13 }).forEach(() => state.menu.move(1))
+    Array.from({ length: 4 }).forEach(() => state.menu.move(-1))
+
+    expect(state.menu.selected()).toBe(9)
+    expect(state.menu.offset()).toBe(7)
+  } finally {
+    state.dispose()
+  }
+})

packages/opencode/test/cli/run/footer.width.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test"
+import { footerWidthPolicy } from "@/cli/cmd/run/footer.width"
+
+describe("run footer width", () => {
+  test("preserves shared dialog and statusline breakpoints", () => {
+    const narrow = footerWidthPolicy(79)
+    expect(narrow.dialog.narrow).toBe(true)
+    expect(narrow.statusline.showActivityMeta).toBe(false)
+    expect(narrow.statusline.showCommandHint).toBe(true)
+    expect(narrow.statusline.showContextHints).toBe(false)
+    expect(narrow.statusline.contextHintLimit).toBe(0)
+    expect(narrow.statusline.showModel).toBe(false)
+
+    const command = footerWidthPolicy(65)
+    expect(command.statusline.showCommandHint).toBe(false)
+
+    const commandHint = footerWidthPolicy(66)
+    expect(commandHint.statusline.showCommandHint).toBe(true)
+
+    const compact = footerWidthPolicy(80)
+    expect(compact.dialog.narrow).toBe(false)
+    expect(compact.statusline.showActivityMeta).toBe(true)
+    expect(compact.statusline.showContextHints).toBe(true)
+    expect(compact.statusline.contextHintLimit).toBe(1)
+    expect(compact.statusline.showModel).toBe(false)
+
+    const model = footerWidthPolicy(120)
+    expect(model.statusline.contextHintLimit).toBe(2)
+    expect(model.statusline.showModel).toBe(true)
+
+    const spacious = footerWidthPolicy(150)
+    expect(spacious.statusline.contextHintLimit).toBeUndefined()
+    expect(spacious.statusline.showModel).toBe(true)
+  })
+})

packages/opencode/test/cli/run/permission.shared.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test"
+import type { PermissionRequest } from "@opencode-ai/sdk/v2"
+import {
+  createPermissionBodyState,
+  permissionAlwaysLines,
+  permissionCancel,
+  permissionEscape,
+  permissionInfo,
+  permissionReject,
+  permissionRun,
+} from "@/cli/cmd/run/permission.shared"
+
+function req(input: Partial<PermissionRequest> = {}): PermissionRequest {
+  return {
+    id: "perm-1",
+    sessionID: "session-1",
+    permission: "read",
+    patterns: [],
+    metadata: {},
+    always: [],
+    ...input,
+  }
+}
+
+describe("run permission shared", () => {
+  test("replies immediately for allow once", () => {
+    const out = permissionRun(createPermissionBodyState("perm-1"), "perm-1", "once")
+
+    expect(out.reply).toEqual({
+      requestID: "perm-1",
+      reply: "once",
+    })
+  })
+
+  test("requires confirmation for allow always", () => {
+    const next = permissionRun(createPermissionBodyState("perm-1"), "perm-1", "always")
+    expect(next.state.stage).toBe("always")
+    expect(next.state.selected).toBe("confirm")
+    expect(next.reply).toBeUndefined()
+
+    expect(permissionRun(next.state, "perm-1", "confirm").reply).toEqual({
+      requestID: "perm-1",
+      reply: "always",
+    })
+
+    expect(permissionRun(next.state, "perm-1", "cancel").state).toMatchObject({
+      stage: "permission",
+      selected: "always",
+    })
+  })
+
+  test("builds trimmed reject replies and stage transitions", () => {
+    const next = permissionRun(createPermissionBodyState("perm-1"), "perm-1", "reject")
+    expect(next.state.stage).toBe("reject")
+
+    const out = permissionReject({ ...next.state, message: "  use rg  " }, "perm-1")
+    expect(out).toEqual({
+      requestID: "perm-1",
+      reply: "reject",
+      message: "use rg",
+    })
+
+    expect(permissionCancel(next.state)).toMatchObject({
+      stage: "permission",
+      selected: "reject",
+    })
+
+    expect(permissionEscape(createPermissionBodyState("perm-1"))).toMatchObject({
+      stage: "reject",
+      selected: "reject",
+    })
+
+    expect(permissionEscape({ ...next.state, stage: "always", selected: "confirm" })).toMatchObject({
+      stage: "permission",
+      selected: "always",
+    })
+  })
+
+  test("maps supported permission types into display info", () => {
+    expect(
+      permissionInfo(
+        req({
+          permission: "bash",
+          metadata: {
+            input: {
+              command: "git status --short",
+            },
+          },
+        }),
+      ),
+    ).toMatchObject({
+      title: "Shell command",
+      lines: ["$ git status --short"],
+    })
+
+    expect(
+      permissionInfo(
+        req({
+          permission: "task",
+          metadata: {
+            description: "investigate stream",
+            subagent_type: "general",
+          },
+        }),
+      ),
+    ).toMatchObject({
+      title: "General Task",
+      lines: ["◉ investigate stream"],
+    })
+
+    expect(
+      permissionInfo(
+        req({
+          permission: "external_directory",
+          patterns: ["/tmp/work/**/*.ts", "/tmp/work/**/*.tsx"],
+        }),
+      ),
+    ).toMatchObject({
+      title: "Access external directory /tmp/work",
+      lines: ["- /tmp/work/**/*.ts", "- /tmp/work/**/*.tsx"],
+    })
+
+    expect(permissionInfo(req({ permission: "doom_loop" }))).toMatchObject({
+      title: "Continue after repeated failures",
+    })
+
+    expect(permissionInfo(req({ permission: "custom_tool" }))).toMatchObject({
+      title: "Call tool custom_tool",
+      lines: ["Tool: custom_tool"],
+    })
+  })
+
+  test("formats always-allow copy for wildcard and explicit patterns", () => {
+    expect(permissionAlwaysLines(req({ permission: "bash", always: ["*"] }))).toEqual([
+      "This will allow bash until OpenCode is restarted.",
+    ])
+
+    expect(permissionAlwaysLines(req({ always: ["src/**/*.ts", "src/**/*.tsx"] }))).toEqual([
+      "This will allow the following patterns until OpenCode is restarted.",
+      "- src/**/*.ts",
+      "- src/**/*.tsx",
+    ])
+  })
+})

packages/opencode/test/cli/run/prompt.editor.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test"
+import { realignEditorPromptParts, resolveEditorSlashValue } from "@/cli/cmd/run/prompt.editor"
+import type { RunPromptPart } from "@/cli/cmd/run/types"
+
+describe("run prompt editor helpers", () => {
+  test("strips the local /editor command from the initial editor text", () => {
+    expect(resolveEditorSlashValue("/editor")).toBe("")
+    expect(resolveEditorSlashValue("/editor draft message")).toBe("draft message")
+    expect(resolveEditorSlashValue("/editor first line\nsecond line")).toBe("first line\nsecond line")
+  })
+
+  test("realigns file and agent parts after external editing", () => {
+    const filePart = {
+      type: "file",
+      mime: "text/plain",
+      filename: "src/app.ts",
+      url: "file:///src/app.ts",
+      source: {
+        type: "file",
+        path: "src/app.ts",
+        text: {
+          start: 0,
+          end: 11,
+          value: "@src/app.ts",
+        },
+      },
+    } satisfies RunPromptPart
+    const agentPart = {
+      type: "agent",
+      name: "helper",
+      source: {
+        start: 12,
+        end: 19,
+        value: "@helper",
+      },
+    } satisfies RunPromptPart
+    const parts = [filePart, agentPart]
+
+    expect(realignEditorPromptParts("Please check @helper before @src/app.ts", parts)).toEqual([
+      {
+        ...filePart,
+        source: {
+          ...filePart.source,
+          text: {
+            ...filePart.source.text,
+            start: 28,
+            end: 39,
+            value: "@src/app.ts",
+          },
+        },
+      },
+      {
+        ...agentPart,
+        source: {
+          start: 13,
+          end: 20,
+          value: "@helper",
+        },
+      },
+    ])
+  })
+
+  test("drops parts whose virtual text was deleted", () => {
+    const filePart = {
+      type: "file",
+      mime: "text/plain",
+      filename: "src/app.ts",
+      url: "file:///src/app.ts",
+      source: {
+        type: "file",
+        path: "src/app.ts",
+        text: {
+          start: 0,
+          end: 11,
+          value: "@src/app.ts",
+        },
+      },
+    } satisfies RunPromptPart
+    const agentPart = {
+      type: "agent",
+      name: "helper",
+      source: {
+        start: 12,
+        end: 19,
+        value: "@helper",
+      },
+    } satisfies RunPromptPart
+    const parts = [filePart, agentPart]
+
+    expect(realignEditorPromptParts("Only @helper remains", parts)).toEqual([
+      {
+        ...agentPart,
+        source: {
+          start: 5,
+          end: 12,
+          value: "@helper",
+        },
+      },
+    ])
+  })
+})

packages/opencode/test/cli/run/prompt.shared.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test"
+import {
+  createPromptHistory,
+  isExitCommand,
+  isNewCommand,
+  movePromptHistory,
+  pushPromptHistory,
+} from "@/cli/cmd/run/prompt.shared"
+import type { RunPrompt } from "@/cli/cmd/run/types"
+
+function prompt(text: string, parts: RunPrompt["parts"] = []): RunPrompt {
+  return { text, parts }
+}
+
+describe("run prompt shared", () => {
+  test("filters blank prompts and dedupes consecutive history", () => {
+    const out = createPromptHistory([prompt("   "), prompt("one"), prompt("one"), prompt("two"), prompt("one")])
+
+    expect(out.items.map((item) => item.text)).toEqual(["one", "two", "one"])
+    expect(out.index).toBeNull()
+    expect(out.draft).toBe("")
+  })
+
+  test("push ignores blanks and dedupes only the latest item", () => {
+    const base = createPromptHistory([prompt("one")])
+
+    expect(pushPromptHistory(base, prompt("   ")).items.map((item) => item.text)).toEqual(["one"])
+    expect(pushPromptHistory(base, prompt("one")).items.map((item) => item.text)).toEqual(["one"])
+    expect(pushPromptHistory(base, prompt("two")).items.map((item) => item.text)).toEqual(["one", "two"])
+  })
+
+  test("moves through history only at input boundaries and restores draft", () => {
+    const base = createPromptHistory([prompt("one"), prompt("two")])
+
+    expect(movePromptHistory(base, -1, "draft", 1)).toEqual({
+      state: base,
+      apply: false,
+    })
+
+    const up = movePromptHistory(base, -1, "draft", 0)
+    expect(up.apply).toBe(true)
+    expect(up.text).toBe("two")
+    expect(up.cursor).toBe(0)
+    expect(up.state.index).toBe(1)
+    expect(up.state.draft).toBe("draft")
+
+    const older = movePromptHistory(up.state, -1, "two", 0)
+    expect(older.apply).toBe(true)
+    expect(older.text).toBe("one")
+    expect(older.cursor).toBe(0)
+    expect(older.state.index).toBe(0)
+
+    const newer = movePromptHistory(older.state, 1, "one", 3)
+    expect(newer.apply).toBe(true)
+    expect(newer.text).toBe("two")
+    expect(newer.cursor).toBe(3)
+    expect(newer.state.index).toBe(1)
+
+    const draft = movePromptHistory(newer.state, 1, "two", 3)
+    expect(draft.apply).toBe(true)
+    expect(draft.text).toBe("draft")
+    expect(draft.cursor).toBe(5)
+    expect(draft.state.index).toBeNull()
+  })
+
+  test("uses display-width cursors for history restoration", () => {
+    const base = createPromptHistory([prompt("one"), prompt("中文")])
+
+    const latest = movePromptHistory(base, -1, "草稿", 0)
+    expect(latest.apply).toBe(true)
+    expect(latest.text).toBe("中文")
+    expect(latest.cursor).toBe(0)
+
+    const older = movePromptHistory(latest.state, -1, "中文", 0)
+    expect(older.apply).toBe(true)
+    expect(older.text).toBe("one")
+    expect(older.cursor).toBe(0)
+
+    const newer = movePromptHistory(older.state, 1, "one", Bun.stringWidth("one"))
+    expect(newer.apply).toBe(true)
+    expect(newer.text).toBe("中文")
+    expect(newer.cursor).toBe(Bun.stringWidth("中文"))
+
+    const draft = movePromptHistory(newer.state, 1, "中文", Bun.stringWidth("中文"))
+    expect(draft.apply).toBe(true)
+    expect(draft.text).toBe("草稿")
+    expect(draft.cursor).toBe(Bun.stringWidth("草稿"))
+  })
+
+  test("recognizes exit commands", () => {
+    expect(isExitCommand("/exit")).toBe(true)
+    expect(isExitCommand(" /Quit ")).toBe(true)
+    expect(isExitCommand("/quit now")).toBe(false)
+  })
+
+  test("recognizes the new-session command", () => {
+    expect(isNewCommand("/new")).toBe(true)
+    expect(isNewCommand(" /NEW ")).toBe(true)
+    expect(isNewCommand("/new now")).toBe(false)
+  })
+})

packages/opencode/test/cli/run/question.shared.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test"
+import type { QuestionRequest } from "@opencode-ai/sdk/v2"
+import {
+  createQuestionBodyState,
+  questionConfirm,
+  questionReject,
+  questionSave,
+  questionSelect,
+  questionSetSelected,
+  questionStoreCustom,
+  questionSubmit,
+  questionSync,
+} from "@/cli/cmd/run/question.shared"
+
+function req(input: Partial<QuestionRequest> = {}): QuestionRequest {
+  return {
+    id: "question-1",
+    sessionID: "session-1",
+    questions: [
+      {
+        question: "Mode?",
+        header: "Mode",
+        options: [{ label: "chunked", description: "Incremental output" }],
+        multiple: false,
+      },
+    ],
+    ...input,
+  }
+}
+
+describe("run question shared", () => {
+  test("replies immediately for a single-select question", () => {
+    const out = questionSelect(createQuestionBodyState("question-1"), req())
+
+    expect(out.reply).toEqual({
+      requestID: "question-1",
+      answers: [["chunked"]],
+    })
+  })
+
+  test("advances multi-question flows and submits from confirm", () => {
+    const ask = req({
+      questions: [
+        {
+          question: "Mode?",
+          header: "Mode",
+          options: [{ label: "chunked", description: "Incremental output" }],
+          multiple: false,
+        },
+        {
+          question: "Output?",
+          header: "Output",
+          options: [
+            { label: "yes", description: "Show tool output" },
+            { label: "no", description: "Hide tool output" },
+          ],
+          multiple: false,
+        },
+      ],
+    })
+
+    let state = questionSelect(createQuestionBodyState("question-1"), ask).state
+    expect(state.tab).toBe(1)
+
+    state = questionSetSelected(state, 1)
+    state = questionSelect(state, ask).state
+    expect(questionConfirm(ask, state)).toBe(true)
+    expect(questionSubmit(ask, state)).toEqual({
+      requestID: "question-1",
+      answers: [["chunked"], ["no"]],
+    })
+  })
+
+  test("toggles answers for multiple-choice questions", () => {
+    const ask = req({
+      questions: [
+        {
+          question: "Tags?",
+          header: "Tags",
+          options: [{ label: "bug", description: "Bug fix" }],
+          multiple: true,
+        },
+      ],
+    })
+
+    let state = questionSelect(createQuestionBodyState("question-1"), ask).state
+    expect(state.answers).toEqual([["bug"]])
+
+    state = questionSelect(state, ask).state
+    expect(state.answers).toEqual([[]])
+  })
+
+  test("stores and submits custom answers", () => {
+    let state = questionSetSelected(createQuestionBodyState("question-1"), 1)
+    let next = questionSelect(state, req())
+    expect(next.state.editing).toBe(true)
+
+    state = questionStoreCustom(next.state, 0, "  custom mode  ")
+    next = questionSave(state, req())
+    expect(next.reply).toEqual({
+      requestID: "question-1",
+      answers: [["custom mode"]],
+    })
+  })
+
+  test("resets state when the request id changes and builds reject payloads", () => {
+    const state = questionSetSelected(createQuestionBodyState("question-1"), 1)
+
+    expect(questionSync(state, "question-1")).toBe(state)
+    expect(questionSync(state, "question-2")).toEqual(createQuestionBodyState("question-2"))
+    expect(questionReject(req())).toEqual({
+      requestID: "question-1",
+    })
+  })
+})

packages/opencode/test/cli/run/run-process.test.ts

@@ -0,0 +1,84 @@
+// Subprocess integration tests for `opencode run` (non-interactive mode).
+// These exercise the real CLI binary against a TestLLMServer running in the
+// same process. See `test/lib/cli-process.ts` for the harness — each test uses
+// `opencode.run(message, opts?)` to spawn `bun src/index.ts run ...` with
+// `OPENCODE_CONFIG_CONTENT` providing the test provider config inline.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode run (non-interactive subprocess)", () => {
+  // Happy path: prompt completes, output reaches stdout, process exits 0.
+  // If this fails, all the others likely will too — debug here first.
+  cliIt.concurrent(
+    "exits 0 and writes the response to stdout on a successful prompt",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.text("hello from the test llm")
+        const result = yield* opencode.run("say hi")
+        opencode.expectExit(result, 0)
+        expect(result.stdout).toContain("hello from the test llm")
+      }),
+    60_000,
+  )
+
+  // Regression for #27371: an unknown model used to hang the process forever
+  // waiting on a session.status === idle event that never arrived. The fix
+  // makes the SDK call surface an error promptly so the process exits nonzero.
+  // We assert nonzero exit AND wall-clock under the harness timeout — a hang
+  // would expire the timeout and produce a different (signal-killed) failure.
+  cliIt.concurrent(
+    "exits nonzero promptly when the model is unknown (regression for #27371)",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const result = yield* opencode.run("say hi", {
+          model: "test/nonexistent-model",
+          timeoutMs: 15_000,
+        })
+        expect(result.exitCode).not.toBe(0)
+        expect(result.durationMs).toBeLessThan(15_000)
+      }),
+    30_000,
+  )
+
+  // Locks in the current behavior: when the LLM stream errors mid-response
+  // (the prompt was accepted, then the upstream provider failed), opencode
+  // emits a session.error event and the process exits 0 today.
+  //
+  // This is debatable — a future cleanup might flip it to exit 1. If you're
+  // changing this expectation, do it deliberately and say so in the PR.
+  cliIt.concurrent(
+    "mid-stream LLM error still exits 0 today (contract lock-in)",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.fail("upstream provider exploded mid-stream")
+        const result = yield* opencode.run("trigger midstream error", { timeoutMs: 30_000 })
+        expect(result.exitCode).toBe(0)
+      }),
+    60_000,
+  )
+
+  // --format json puts one JSON object per line on stdout for each emitted
+  // event. Consumers (CI scripts, tooling) parse this stream. Asserts the
+  // shape so a future event-emit change has to update this expectation.
+  cliIt.concurrent(
+    "--format json emits parseable line-delimited JSON to stdout",
+    ({ llm, opencode }) =>
+      Effect.gen(function* () {
+        yield* llm.text("structured output")
+        const result = yield* opencode.run("say hi", { format: "json" })
+        opencode.expectExit(result, 0)
+
+        const events = opencode.parseJsonEvents(result.stdout)
+        expect(events.length).toBeGreaterThan(0)
+        for (const evt of events) {
+          expect(typeof evt.type).toBe("string")
+          expect(typeof evt.sessionID).toBe("string")
+        }
+        // At least one `text` event should appear with the LLM's response.
+        const text = events.find((e) => e.type === "text")
+        expect(text).toBeDefined()
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/run/runtime.boot.test.ts

@@ -0,0 +1,283 @@
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test"
+import { OpencodeClient, type Provider } from "@opencode-ai/sdk/v2"
+import type { Resolved } from "@opencode-ai/tui/config"
+import { TuiConfig } from "@/config/tui"
+import { resolveDiffStyle, resolveModelInfo, resolveRunTuiConfig } from "@/cli/cmd/run/runtime.boot"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+
+function model(id: string, providerID: string, context: number, variants?: Record<string, Record<string, never>>) {
+  return {
+    id,
+    providerID,
+    api: {
+      id: providerID,
+      url: `https://${providerID}.test`,
+      npm: `@ai-sdk/${providerID}`,
+    },
+    name: id,
+    capabilities: {
+      temperature: true,
+      reasoning: true,
+      attachment: true,
+      toolcall: true,
+      input: {
+        text: true,
+        audio: false,
+        image: false,
+        video: false,
+        pdf: false,
+      },
+      output: {
+        text: true,
+        audio: false,
+        image: false,
+        video: false,
+        pdf: false,
+      },
+      interleaved: false,
+    },
+    cost: {
+      input: 0,
+      output: 0,
+      cache: {
+        read: 0,
+        write: 0,
+      },
+    },
+    limit: {
+      context,
+      output: 8192,
+    },
+    status: "active" as const,
+    options: {},
+    headers: {},
+    release_date: "2026-01-01",
+    variants,
+  }
+}
+
+function config(input?: {
+  leader?: string
+  leaderTimeout?: number
+  diff_style?: "auto" | "stacked"
+  bindings?: Partial<{
+    commandList: string[]
+    variantCycle: string[]
+    interrupt: string[]
+    historyPrevious: string[]
+    historyNext: string[]
+    inputClear: string[]
+    inputSubmit: string[]
+    inputNewline: string[]
+  }>
+}): Resolved {
+  const bind = input?.bindings
+  return createTuiResolvedConfig({
+    diff_style: input?.diff_style,
+    leader_timeout: input?.leaderTimeout,
+    keybinds: {
+      ...(input?.leader && { leader: input.leader }),
+      ...(bind?.commandList && { command_list: bind.commandList }),
+      ...(bind?.variantCycle && { variant_cycle: bind.variantCycle }),
+      ...(bind?.interrupt && { session_interrupt: bind.interrupt }),
+      ...(bind?.historyPrevious && { history_previous: bind.historyPrevious }),
+      ...(bind?.historyNext && { history_next: bind.historyNext }),
+      ...(bind?.inputClear && { input_clear: bind.inputClear }),
+      ...(bind?.inputSubmit && { input_submit: bind.inputSubmit }),
+      ...(bind?.inputNewline && { input_newline: bind.inputNewline }),
+    },
+  })
+}
+
+describe("run runtime boot", () => {
+  afterEach(() => {
+    mock.restore()
+  })
+
+  test("reads footer keybinds from resolved keybind config", async () => {
+    spyOn(TuiConfig, "get").mockResolvedValue(
+      config({
+        leader: "ctrl+g",
+        bindings: {
+          commandList: ["ctrl+p"],
+          variantCycle: ["ctrl+t", "alt+t"],
+          interrupt: ["ctrl+c"],
+          historyPrevious: ["k"],
+          historyNext: ["j"],
+          inputClear: ["ctrl+l"],
+          inputSubmit: ["ctrl+s"],
+          inputNewline: ["alt+return"],
+        },
+      }),
+    )
+
+    const result = await resolveRunTuiConfig()
+
+    expect(result.keybinds.get("leader")?.[0]?.key).toBe("ctrl+g")
+    expect(result.leader_timeout).toBe(2000)
+    expect(result.keybinds.get("command.palette.show")?.[0]?.key).toBe("ctrl+p")
+    expect(result.keybinds.get("variant.cycle").map((item) => item.key)).toEqual(["ctrl+t", "alt+t"])
+    expect(result.keybinds.get("session.interrupt")?.[0]?.key).toBe("ctrl+c")
+    expect(result.keybinds.get("prompt.history.previous")?.[0]?.key).toBe("k")
+    expect(result.keybinds.get("prompt.history.next")?.[0]?.key).toBe("j")
+    expect(result.keybinds.get("prompt.clear")?.[0]?.key).toBe("ctrl+l")
+    expect(result.keybinds.get("input.submit")?.[0]?.key).toBe("ctrl+s")
+    expect(result.keybinds.get("input.newline")?.[0]?.key).toBe("alt+return")
+  })
+
+  test("falls back to default tui keymap config when config load fails", async () => {
+    spyOn(TuiConfig, "get").mockRejectedValue(new Error("boom"))
+
+    const result = await resolveRunTuiConfig()
+
+    expect(result.keybinds.get("leader")?.[0]?.key).toBe("ctrl+x")
+    expect(result.leader_timeout).toBe(2000)
+    expect(result.diff_style).toBe("auto")
+    expect(result.keybinds.get("command.palette.show")?.[0]?.key).toBe("ctrl+p")
+    expect(result.keybinds.get("variant.cycle")?.[0]?.key).toBe("ctrl+t")
+    expect(result.keybinds.get("session.interrupt")?.[0]?.key).toBe("escape")
+    expect(result.keybinds.get("prompt.history.previous")?.[0]?.key).toBe("up")
+    expect(result.keybinds.get("prompt.history.next")?.[0]?.key).toBe("down")
+    expect(result.keybinds.get("prompt.clear")?.[0]?.key).toBe("ctrl+c")
+    expect(result.keybinds.get("input.submit")?.[0]?.key).toBe("return")
+    expect(result.keybinds.get("input.newline")?.[0]?.key).toBe("shift+return,ctrl+return,alt+return,ctrl+j")
+  })
+
+  test("preserves disabled leader from resolved tui config", async () => {
+    spyOn(TuiConfig, "get").mockResolvedValue(config({ leader: "none" }))
+
+    const result = await resolveRunTuiConfig()
+
+    expect(result.keybinds.get("leader")).toEqual([])
+  })
+
+  test("reads diff style and falls back to auto", async () => {
+    spyOn(TuiConfig, "get").mockResolvedValue(config({ diff_style: "stacked" }))
+    await expect(resolveDiffStyle()).resolves.toBe("stacked")
+
+    mock.restore()
+    spyOn(TuiConfig, "get").mockRejectedValue(new Error("boom"))
+    await expect(resolveDiffStyle()).resolves.toBe("auto")
+  })
+
+  test("prefers configured providers for model selector data", async () => {
+    const sdk = new OpencodeClient()
+    const data: {
+      all: Provider[]
+      default: Record<string, string>
+      connected: string[]
+    } = {
+      all: [
+        {
+          id: "openai",
+          name: "OpenAI",
+          source: "api",
+          env: [],
+          options: {},
+          models: {
+            "gpt-5": model("gpt-5", "openai", 128000, {
+              high: {},
+              minimal: {},
+            }),
+          },
+        },
+        {
+          id: "anthropic",
+          name: "Anthropic",
+          source: "api",
+          env: [],
+          options: {},
+          models: {
+            sonnet: model("sonnet", "anthropic", 200000),
+          },
+        },
+      ],
+      default: {},
+      connected: [],
+    }
+    const configured = {
+      providers: [data.all[0]!],
+      default: {},
+    }
+    const list = spyOn(sdk.provider, "list").mockImplementation(() =>
+      Promise.resolve({
+        data,
+        error: undefined,
+        request: new Request("https://opencode.test"),
+        response: new Response(),
+      }),
+    )
+    spyOn(sdk.config, "providers").mockImplementation(() =>
+      Promise.resolve({
+        data: configured,
+        error: undefined,
+        request: new Request("https://opencode.test"),
+        response: new Response(),
+      }),
+    )
+
+    await expect(resolveModelInfo(sdk, "/workspace", { providerID: "openai", modelID: "gpt-5" })).resolves.toEqual({
+      providers: configured.providers,
+      variants: ["high", "minimal"],
+      limits: {
+        "openai/gpt-5": 128000,
+      },
+    })
+    expect(list).not.toHaveBeenCalled()
+  })
+
+  test("falls back to provider list when configured providers are unavailable", async () => {
+    const sdk = new OpencodeClient()
+    const data: {
+      all: Provider[]
+      default: Record<string, string>
+      connected: string[]
+    } = {
+      all: [
+        {
+          id: "openai",
+          name: "OpenAI",
+          source: "api",
+          env: [],
+          options: {},
+          models: {
+            "gpt-5": model("gpt-5", "openai", 128000, {
+              high: {},
+              minimal: {},
+            }),
+          },
+        },
+        {
+          id: "anthropic",
+          name: "Anthropic",
+          source: "api",
+          env: [],
+          options: {},
+          models: {
+            sonnet: model("sonnet", "anthropic", 200000),
+          },
+        },
+      ],
+      default: {},
+      connected: [],
+    }
+    spyOn(sdk.config, "providers").mockRejectedValue(new Error("boom"))
+    spyOn(sdk.provider, "list").mockImplementation(() =>
+      Promise.resolve({
+        data,
+        error: undefined,
+        request: new Request("https://opencode.test"),
+        response: new Response(),
+      }),
+    )
+
+    await expect(resolveModelInfo(sdk, "/workspace", { providerID: "openai", modelID: "gpt-5" })).resolves.toEqual({
+      providers: data.all,
+      variants: ["high", "minimal"],
+      limits: {
+        "openai/gpt-5": 128000,
+        "anthropic/sonnet": 200000,
+      },
+    })
+  })
+})

packages/opencode/test/cli/run/runtime.queue.test.ts

@@ -0,0 +1,481 @@
+import { describe, expect, test } from "bun:test"
+import { runPromptQueue } from "@/cli/cmd/run/runtime.queue"
+import type { FooterApi, FooterEvent, RunPrompt, StreamCommit } from "@/cli/cmd/run/types"
+
+function footer() {
+  const prompts = new Set<(input: RunPrompt) => void>()
+  const queuedRemoves = new Set<(messageID: string) => void>()
+  const closes = new Set<() => void>()
+  const events: FooterEvent[] = []
+  const commits: StreamCommit[] = []
+  let closed = false
+
+  const api: FooterApi = {
+    get isClosed() {
+      return closed
+    },
+    onPrompt(fn) {
+      prompts.add(fn)
+      return () => {
+        prompts.delete(fn)
+      }
+    },
+    onQueuedRemove(fn) {
+      queuedRemoves.add(fn)
+      return () => {
+        queuedRemoves.delete(fn)
+      }
+    },
+    onClose(fn) {
+      if (closed) {
+        fn()
+        return () => {}
+      }
+
+      closes.add(fn)
+      return () => {
+        closes.delete(fn)
+      }
+    },
+    event(next) {
+      events.push(next)
+    },
+    append(next) {
+      commits.push(next)
+    },
+    idle() {
+      return Promise.resolve()
+    },
+    close() {
+      if (closed) {
+        return
+      }
+
+      closed = true
+      for (const fn of [...closes]) {
+        fn()
+      }
+    },
+    destroy() {
+      api.close()
+      prompts.clear()
+      closes.clear()
+    },
+  }
+
+  return {
+    api,
+    events,
+    commits,
+    submit(text: string, mode?: RunPrompt["mode"]) {
+      const next = mode ? { text, parts: [] as RunPrompt["parts"], mode } : { text, parts: [] as RunPrompt["parts"] }
+      for (const fn of [...prompts]) {
+        fn(next)
+      }
+    },
+    removeQueued(messageID: string) {
+      for (const fn of [...queuedRemoves]) fn(messageID)
+    },
+  }
+}
+
+describe("run runtime queue", () => {
+  test("ignores empty prompts", async () => {
+    const ui = footer()
+    let calls = 0
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async () => {
+        calls += 1
+      },
+    })
+
+    ui.submit("   ")
+    ui.api.close()
+    await task
+
+    expect(calls).toBe(0)
+  })
+
+  test("treats /exit as a close command", async () => {
+    const ui = footer()
+    let calls = 0
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async () => {
+        calls += 1
+      },
+    })
+
+    ui.submit("/exit")
+    await task
+
+    expect(calls).toBe(0)
+  })
+
+  test("treats /new as a local session command", async () => {
+    const ui = footer()
+    const seen: string[] = []
+    let created = 0
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      onNewSession: async () => {
+        created += 1
+      },
+      run: async (input) => {
+        seen.push(input.text)
+        ui.api.close()
+      },
+    })
+
+    ui.submit("/new")
+    ui.submit("hello")
+    await task
+
+    expect(created).toBe(1)
+    expect(seen).toEqual(["hello"])
+    expect(ui.commits).toEqual([
+      {
+        kind: "user",
+        text: "hello",
+        phase: "start",
+        source: "system",
+        messageID: expect.any(String),
+      },
+    ])
+  })
+
+  test("shell mode submits /exit as a shell command", async () => {
+    const ui = footer()
+    const seen: RunPrompt[] = []
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input) => {
+        seen.push(input)
+        ui.api.close()
+      },
+    })
+
+    ui.submit("/exit", "shell")
+    await task
+
+    expect(seen).toEqual([{ text: "/exit", parts: [], mode: "shell" }])
+    expect(ui.commits).toEqual([])
+  })
+
+  test("shell mode submits /new instead of creating a session", async () => {
+    const ui = footer()
+    const seen: RunPrompt[] = []
+    let created = 0
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      onNewSession: async () => {
+        created += 1
+      },
+      run: async (input) => {
+        seen.push(input)
+        ui.api.close()
+      },
+    })
+
+    ui.submit("/new", "shell")
+    await task
+
+    expect(created).toBe(0)
+    expect(seen).toEqual([{ text: "/new", parts: [], mode: "shell" }])
+    expect(ui.commits).toEqual([])
+  })
+
+  test("shell mode does not append a synthetic user row", async () => {
+    const ui = footer()
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async () => {
+        expect(ui.commits).toEqual([])
+        ui.api.close()
+      },
+    })
+
+    ui.submit("ls", "shell")
+    await task
+  })
+
+  test("shell mode does not emit a turn duration summary", async () => {
+    const ui = footer()
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async () => {
+        ui.api.close()
+      },
+    })
+
+    ui.submit("ls", "shell")
+    await task
+
+    expect(ui.events.some((event) => event.type === "turn.duration")).toBe(false)
+  })
+
+  test("preserves whitespace for initial input", async () => {
+    const ui = footer()
+    const seen: string[] = []
+
+    await runPromptQueue({
+      footer: ui.api,
+      initialInput: "  hello  ",
+      run: async (input) => {
+        seen.push(input.text)
+        ui.api.close()
+      },
+    })
+
+    expect(seen).toEqual(["  hello  "])
+    expect(ui.commits).toEqual([
+      {
+        kind: "user",
+        text: "  hello  ",
+        phase: "start",
+        source: "system",
+        messageID: expect.any(String),
+      },
+    ])
+  })
+
+  test("passes prompts to onSend", async () => {
+    const ui = footer()
+    const seen: string[] = []
+
+    await runPromptQueue({
+      footer: ui.api,
+      initialInput: "  hello  ",
+      onSend: (input) => {
+        seen.push(input.text)
+      },
+      run: async () => {
+        ui.api.close()
+      },
+    })
+
+    expect(seen).toEqual(["  hello  "])
+  })
+
+  test("appends the user row before the turn starts", async () => {
+    const ui = footer()
+
+    await runPromptQueue({
+      footer: ui.api,
+      initialInput: "/fmt bash",
+      run: async () => {
+        expect(ui.commits).toEqual([
+          {
+            kind: "user",
+            text: "/fmt bash",
+            phase: "start",
+            source: "system",
+            messageID: expect.any(String),
+          },
+        ])
+        ui.api.close()
+      },
+    })
+  })
+
+  test("runs queued prompts in order", async () => {
+    const ui = footer()
+    const seen: string[] = []
+    let wake: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => {
+      wake = resolve
+    })
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input) => {
+        seen.push(input.text)
+        if (seen.length === 1) {
+          await gate
+          return
+        }
+
+        ui.api.close()
+      },
+    })
+
+    ui.submit("one")
+    ui.submit("two")
+    await Promise.resolve()
+    expect(seen).toEqual(["one"])
+
+    wake?.()
+    await task
+
+    expect(seen).toEqual(["one", "two"])
+  })
+
+  test("exposes ordinary in-flight prompts for removal before sending", async () => {
+    const ui = footer()
+    const turns: RunPrompt[] = []
+    let wake: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => {
+      wake = resolve
+    })
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input) => {
+        turns.push(input)
+        await gate
+      },
+    })
+
+    ui.submit("one")
+    ui.submit("two")
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(turns.map((item) => item.text)).toEqual(["one"])
+    expect(turns[0]?.messageID).toEqual(expect.any(String))
+    expect(ui.commits.map((item) => item.text)).toEqual(["one"])
+    const first = ui.events.find((item) => item.type === "queued.prompts")
+    const event = ui.events.findLast((item) => item.type === "queued.prompts")
+    expect(first?.type === "queued.prompts" ? first.prompts : []).toEqual([])
+    expect(
+      first?.type === "queued.prompts" && event?.type === "queued.prompts" ? first.prompts === event.prompts : true,
+    ).toBe(false)
+    expect(ui.events.findLast((item) => item.type === "queue")).toEqual({ type: "queue", queue: 1 })
+    expect(event?.type === "queued.prompts" ? event.prompts.map((item) => item.prompt.text) : []).toEqual(["two"])
+    if (event?.type === "queued.prompts") ui.removeQueued(event.prompts[0]!.messageID)
+    await Promise.resolve()
+
+    wake?.()
+    ui.api.close()
+    await task
+    expect(turns.map((item) => item.text)).toEqual(["one"])
+  })
+
+  test("removing one managed queued prompt preserves the others", async () => {
+    const ui = footer()
+    const turns: string[] = []
+    let wake: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => {
+      wake = resolve
+    })
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input) => {
+        turns.push(input.text)
+        if (input.text === "active") await gate
+        if (input.text === "queued three") ui.api.close()
+      },
+    })
+
+    ui.submit("active")
+    ui.submit("queued one")
+    ui.submit("queued two")
+    ui.submit("queued three")
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const event = ui.events.findLast((item) => item.type === "queued.prompts")
+    if (event?.type === "queued.prompts") {
+      const second = event.prompts.find((item) => item.prompt.text === "queued two")
+      if (second) ui.removeQueued(second.messageID)
+    }
+
+    wake?.()
+    await task
+    expect(turns).toEqual(["active", "queued one", "queued three"])
+  })
+
+  test("drains a prompt queued during an in-flight turn", async () => {
+    const ui = footer()
+    const seen: string[] = []
+    let wake: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => {
+      wake = resolve
+    })
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input) => {
+        seen.push(input.text)
+        if (seen.length === 1) {
+          await gate
+          return
+        }
+
+        ui.api.close()
+      },
+    })
+
+    ui.submit("one")
+    await Promise.resolve()
+    expect(seen).toEqual(["one"])
+
+    wake?.()
+    await Promise.resolve()
+    ui.submit("two")
+    await task
+
+    expect(seen).toEqual(["one", "two"])
+  })
+
+  test("close aborts the active run and drops pending queued work", async () => {
+    const ui = footer()
+    const seen: string[] = []
+    let hit = false
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async (input, signal) => {
+        seen.push(input.text)
+        await new Promise<void>((resolve) => {
+          if (signal.aborted) {
+            hit = true
+            resolve()
+            return
+          }
+
+          signal.addEventListener(
+            "abort",
+            () => {
+              hit = true
+              resolve()
+            },
+            { once: true },
+          )
+        })
+      },
+    })
+
+    ui.submit("one")
+    await Promise.resolve()
+    ui.submit("two")
+    ui.api.close()
+    await task
+
+    expect(hit).toBe(true)
+    expect(seen).toEqual(["one"])
+  })
+
+  test("propagates run errors", async () => {
+    const ui = footer()
+
+    const task = runPromptQueue({
+      footer: ui.api,
+      run: async () => {
+        throw new Error("boom")
+      },
+    })
+
+    ui.submit("one")
+    await expect(task).rejects.toThrow("boom")
+  })
+})

packages/opencode/test/cli/run/runtime.stdin.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test"
+import { Readable } from "node:stream"
+import { INTERACTIVE_INPUT_ERROR, resolveInteractiveStdin } from "@/cli/cmd/run/runtime.stdin"
+
+function stream(isTTY: boolean) {
+  return Object.assign(new Readable({ read() {} }), { isTTY }) as NodeJS.ReadStream
+}
+
+describe("run interactive stdin", () => {
+  test("reuses stdin when it is already a tty", () => {
+    const stdin = stream(true)
+    const seen: string[] = []
+    const result = resolveInteractiveStdin(
+      stdin,
+      (path) => {
+        seen.push(path)
+        return stream(true)
+      },
+      "linux",
+    )
+
+    expect(result.stdin).toBe(stdin)
+    expect(result.cleanup).toBeUndefined()
+    expect(seen).toEqual([])
+  })
+
+  test("opens the controlling terminal when stdin is piped", () => {
+    const tty = stream(true)
+    const seen: string[] = []
+    const result = resolveInteractiveStdin(
+      stream(false),
+      (path) => {
+        seen.push(path)
+        return tty
+      },
+      "linux",
+    )
+
+    expect(result.stdin).toBe(tty)
+    expect(seen).toEqual(["/dev/tty"])
+
+    result.cleanup?.()
+    expect(tty.destroyed).toBe(true)
+  })
+
+  test("uses CONIN$ on windows", () => {
+    const seen: string[] = []
+    resolveInteractiveStdin(
+      stream(false),
+      (path) => {
+        seen.push(path)
+        return stream(true)
+      },
+      "win32",
+    )
+
+    expect(seen).toEqual(["CONIN$"])
+  })
+
+  test("throws a clear error when no controlling terminal is available", () => {
+    expect(() =>
+      resolveInteractiveStdin(
+        stream(false),
+        () => {
+          throw new Error("open failed")
+        },
+        "linux",
+      ),
+    ).toThrow(INTERACTIVE_INPUT_ERROR)
+  })
+})

packages/opencode/test/cli/run/runtime.test.ts

@@ -0,0 +1,238 @@
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test"
+import { OpencodeClient } from "@opencode-ai/sdk/v2"
+import { runInteractiveMode } from "@/cli/cmd/run/runtime"
+import type { FooterApi, RunProvider } from "@/cli/cmd/run/types"
+
+type SessionMessage = NonNullable<Awaited<ReturnType<OpencodeClient["session"]["messages"]>>["data"]>[number]
+
+const provider: RunProvider = {
+  id: "openai",
+  name: "OpenAI",
+  source: "api",
+  env: [],
+  options: {},
+  models: {
+    "gpt-5": {
+      id: "gpt-5",
+      providerID: "openai",
+      api: {
+        id: "openai",
+        url: "https://openai.test",
+        npm: "@ai-sdk/openai",
+      },
+      name: "Little Frank",
+      capabilities: {
+        temperature: true,
+        reasoning: true,
+        attachment: true,
+        toolcall: true,
+        input: {
+          text: true,
+          audio: false,
+          image: false,
+          video: false,
+          pdf: false,
+        },
+        output: {
+          text: true,
+          audio: false,
+          image: false,
+          video: false,
+          pdf: false,
+        },
+        interleaved: false,
+      },
+      cost: {
+        input: 0,
+        output: 0,
+        cache: {
+          read: 0,
+          write: 0,
+        },
+      },
+      limit: {
+        context: 128000,
+        output: 8192,
+      },
+      status: "active",
+      options: {},
+      headers: {},
+      release_date: "2026-01-01",
+    },
+  },
+}
+
+const transportProviders: RunProvider[][] = []
+
+function defer<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+function ok<T>(data: T) {
+  return Promise.resolve({
+    data,
+    error: undefined,
+    request: new Request("https://opencode.test"),
+    response: new Response(),
+  })
+}
+
+function footer(): FooterApi {
+  let closed = false
+  const closes = new Set<() => void>()
+
+  const notify = () => {
+    for (const fn of closes) fn()
+  }
+
+  return {
+    get isClosed() {
+      return closed
+    },
+    onPrompt: () => () => {},
+    onQueuedRemove: () => () => {},
+    onClose(fn) {
+      if (closed) {
+        fn()
+        return () => {}
+      }
+
+      closes.add(fn)
+      return () => {
+        closes.delete(fn)
+      }
+    },
+    event() {},
+    append() {},
+    idle() {
+      return Promise.resolve()
+    },
+    close() {
+      if (closed) {
+        return
+      }
+
+      closed = true
+      notify()
+    },
+    destroy() {
+      if (closed) {
+        return
+      }
+
+      closed = true
+      notify()
+    },
+  }
+}
+
+afterEach(() => {
+  mock.restore()
+  transportProviders.length = 0
+})
+
+describe("run interactive runtime", () => {
+  test("waits for provider metadata before eager replay transport bootstrap", async () => {
+    const providersStarted = defer<void>()
+    const providers = defer<void>()
+
+    const sdk = new OpencodeClient()
+    spyOn(sdk.config, "providers").mockImplementation(async () => {
+      providersStarted.resolve()
+      await providers.promise
+      return ok({ providers: [provider], default: {} })
+    })
+    spyOn(sdk.session, "messages").mockImplementation(() =>
+      ok([
+        {
+          info: {
+            id: "msg-user-1",
+            sessionID: "ses-1",
+            role: "user",
+            time: {
+              created: 1,
+            },
+            agent: "build",
+            model: {
+              providerID: "openai",
+              modelID: "gpt-5",
+              variant: undefined,
+            },
+          },
+          parts: [
+            {
+              id: "part-user-1",
+              sessionID: "ses-1",
+              messageID: "msg-user-1",
+              type: "text",
+              text: "hello",
+            },
+          ],
+        } satisfies SessionMessage,
+      ]),
+    )
+    spyOn(sdk.session, "get").mockRejectedValue(new Error("not needed"))
+    spyOn(sdk.app, "agents").mockImplementation(() => ok([]))
+    spyOn(sdk.experimental.resource, "list").mockImplementation(() => ok({}))
+    spyOn(sdk.command, "list").mockImplementation(() => ok([]))
+
+    const task = runInteractiveMode(
+      {
+        sdk,
+        directory: "/tmp",
+        sessionID: "ses-1",
+        sessionTitle: "Session",
+        resume: true,
+        replay: true,
+        replayLimit: 100,
+        agent: "build",
+        model: {
+          providerID: "openai",
+          modelID: "gpt-5",
+        },
+        variant: undefined,
+        files: [],
+        thinking: true,
+        backgroundSubagents: false,
+      },
+      {
+        createRuntimeLifecycle: async () => ({
+          footer: footer(),
+          onResize: () => () => {},
+          refreshTheme: () => {},
+          resetForReplay: () => Promise.resolve(),
+          close: () => Promise.resolve(),
+        }),
+        streamTransport: Promise.resolve({
+          createSessionTransport: async (input: { providers?: () => RunProvider[]; footer: FooterApi }) => {
+            transportProviders.push(input.providers?.() ?? [])
+            setTimeout(() => {
+              input.footer.close()
+            }, 0)
+            return {
+              runPromptTurn: async () => {},
+              selectSubagent: () => {},
+              replayOnResize: async () => false,
+              close: async () => {},
+            }
+          },
+          formatUnknownError: (error: unknown) => (error instanceof Error ? error.message : String(error)),
+        }),
+      },
+    )
+
+    await providersStarted.promise
+
+    expect(transportProviders).toEqual([])
+
+    providers.resolve()
+
+    await task
+
+    expect(transportProviders).toEqual([[provider]])
+  })
+})

packages/opencode/test/cli/run/session-data.test.ts

@@ -0,0 +1,595 @@
+import { describe, expect, test } from "bun:test"
+import type { Event } from "@opencode-ai/sdk/v2"
+import { createSessionData, flushInterrupted, reduceSessionData } from "@/cli/cmd/run/session-data"
+import type { StreamCommit } from "@/cli/cmd/run/types"
+
+function reduce(data: ReturnType<typeof createSessionData>, event: unknown, thinking = true) {
+  return reduceSessionData({
+    data,
+    event: event as Event,
+    sessionID: "session-1",
+    thinking,
+    limits: {},
+  })
+}
+
+function assistant(id: string, extra: Record<string, unknown> = {}) {
+  return {
+    type: "message.updated",
+    properties: {
+      sessionID: "session-1",
+      info: {
+        id,
+        role: "assistant",
+        providerID: "openai",
+        modelID: "gpt-5",
+        tokens: {
+          input: 1,
+          output: 1,
+          reasoning: 0,
+          cache: { read: 0, write: 0 },
+        },
+        ...extra,
+      },
+    },
+  }
+}
+
+function user(id: string) {
+  return {
+    type: "message.updated",
+    properties: {
+      sessionID: "session-1",
+      info: {
+        id,
+        role: "user",
+      },
+    },
+  }
+}
+
+function text(input: { id: string; messageID: string; text: string; time?: Record<string, number> }) {
+  return {
+    type: "message.part.updated",
+    properties: {
+      part: {
+        id: input.id,
+        messageID: input.messageID,
+        sessionID: "session-1",
+        type: "text",
+        text: input.text,
+        ...(input.time ? { time: input.time } : {}),
+      },
+    },
+  }
+}
+
+function reasoning(input: { id: string; messageID: string; text: string; time?: Record<string, number> }) {
+  return {
+    type: "message.part.updated",
+    properties: {
+      part: {
+        id: input.id,
+        messageID: input.messageID,
+        sessionID: "session-1",
+        type: "reasoning",
+        text: input.text,
+        ...(input.time ? { time: input.time } : {}),
+      },
+    },
+  }
+}
+
+function delta(messageID: string, partID: string, value: string) {
+  return {
+    type: "message.part.delta",
+    properties: {
+      sessionID: "session-1",
+      messageID,
+      partID,
+      field: "text",
+      delta: value,
+    },
+  }
+}
+
+function tool(input: { id: string; messageID: string; tool: string; state: Record<string, unknown>; callID?: string }) {
+  return {
+    type: "message.part.updated",
+    properties: {
+      part: {
+        id: input.id,
+        messageID: input.messageID,
+        sessionID: "session-1",
+        type: "tool",
+        tool: input.tool,
+        ...(input.callID ? { callID: input.callID } : {}),
+        state: input.state,
+      },
+    },
+  }
+}
+
+describe("run session data", () => {
+  test("buffers delayed assistant text until the role is known", () => {
+    let data = createSessionData()
+    data = reduce(data, delta("msg-1", "txt-1", "hello")).data
+    data = reduce(data, assistant("msg-1")).data
+
+    const out = reduce(
+      data,
+      text({
+        id: "txt-1",
+        messageID: "msg-1",
+        text: "",
+        time: { end: 1 },
+      }),
+    )
+
+    expect(out.commits).toEqual([
+      expect.objectContaining({
+        kind: "assistant",
+        text: "hello",
+        partID: "txt-1",
+      }),
+    ])
+  })
+
+  test("keeps leading whitespace buffered until real assistant content arrives", () => {
+    let data = createSessionData()
+    data = reduce(data, assistant("msg-1")).data
+    data = reduce(data, text({ id: "txt-1", messageID: "msg-1", text: "", time: { start: 1 } })).data
+
+    let out = reduce(data, delta("msg-1", "txt-1", " "))
+    expect(out.commits).toEqual([])
+
+    out = reduce(out.data, delta("msg-1", "txt-1", "Found"))
+    expect(out.commits).toEqual([
+      expect.objectContaining({
+        kind: "assistant",
+        text: " Found",
+      }),
+    ])
+  })
+
+  test("drops delayed text once the message resolves to a user role", () => {
+    let data = createSessionData()
+    data = reduce(data, text({ id: "txt-user-1", messageID: "msg-user-1", text: "HELLO", time: { end: 1 } })).data
+
+    const out = reduce(data, user("msg-user-1"))
+
+    expect(out.commits).toEqual([])
+    expect(out.data.ids.has("txt-user-1")).toBe(true)
+  })
+
+  test("suppresses reasoning commits when thinking is disabled", () => {
+    const out = reduce(
+      createSessionData(),
+      reasoning({
+        id: "reason-1",
+        messageID: "msg-1",
+        text: "hidden",
+        time: { end: 1 },
+      }),
+      false,
+    )
+
+    expect(out.commits).toEqual([])
+    expect(out.data.ids.has("reason-1")).toBe(true)
+  })
+
+  test("keeps permission precedence over queued questions", () => {
+    let data = createSessionData()
+    data = reduce(data, {
+      type: "permission.asked",
+      properties: {
+        id: "perm-1",
+        sessionID: "session-1",
+        permission: "read",
+        patterns: ["/tmp/file.txt"],
+        metadata: {},
+        always: [],
+      },
+    }).data
+
+    const ask = reduce(data, {
+      type: "question.asked",
+      properties: {
+        id: "question-1",
+        sessionID: "session-1",
+        questions: [
+          {
+            question: "Mode?",
+            header: "Mode",
+            options: [{ label: "chunked", description: "Incremental output" }],
+            multiple: false,
+          },
+        ],
+      },
+    })
+
+    expect(ask.footer).toEqual({
+      patch: { status: "awaiting permission" },
+      view: {
+        type: "permission",
+        request: expect.objectContaining({ id: "perm-1" }),
+      },
+    })
+
+    expect(
+      reduce(ask.data, {
+        type: "permission.replied",
+        properties: {
+          sessionID: "session-1",
+          requestID: "perm-1",
+          reply: "reject",
+        },
+      }).footer,
+    ).toEqual({
+      patch: { status: "awaiting answer" },
+      view: {
+        type: "question",
+        request: expect.objectContaining({ id: "question-1" }),
+      },
+    })
+  })
+
+  test("refreshes the active permission view when tool input arrives later", () => {
+    const data = reduce(createSessionData(), {
+      type: "permission.asked",
+      properties: {
+        id: "perm-1",
+        sessionID: "session-1",
+        permission: "bash",
+        patterns: ["src/**/*.ts"],
+        metadata: {},
+        always: [],
+        tool: {
+          messageID: "msg-1",
+          callID: "call-1",
+        },
+      },
+    }).data
+
+    const out = reduce(
+      data,
+      tool({
+        id: "tool-1",
+        messageID: "msg-1",
+        callID: "call-1",
+        tool: "bash",
+        state: {
+          status: "running",
+          input: {
+            command: "git status --short",
+          },
+        },
+      }),
+    )
+
+    expect(out.footer).toEqual({
+      view: {
+        type: "permission",
+        request: expect.objectContaining({
+          id: "perm-1",
+          metadata: expect.objectContaining({
+            input: {
+              command: "git status --short",
+            },
+          }),
+        }),
+      },
+    })
+  })
+
+  test("strips bash echo only from the first assistant flush", () => {
+    let data = createSessionData()
+    data = reduce(data, assistant("msg-1")).data
+    data = reduce(
+      data,
+      tool({
+        id: "tool-1",
+        messageID: "msg-1",
+        tool: "bash",
+        state: {
+          status: "completed",
+          input: {
+            command: "printf hi",
+          },
+          output: "echoed\n",
+          time: { start: 1, end: 2 },
+        },
+      }),
+    ).data
+
+    const first = reduce(
+      data,
+      text({
+        id: "txt-1",
+        messageID: "msg-1",
+        text: "echoed\nanswer",
+      }),
+    )
+
+    expect(first.commits).toEqual([
+      expect.objectContaining({
+        kind: "assistant",
+        text: "answer",
+      }),
+    ])
+
+    expect(reduce(first.data, delta("msg-1", "txt-1", "\nechoed\nagain")).commits).toEqual([
+      expect.objectContaining({
+        kind: "assistant",
+        text: "\nechoed\nagain",
+      }),
+    ])
+  })
+
+  test("renders direct shell mode from first-class shell events", () => {
+    let data = createSessionData()
+    const started = reduce(data, {
+      type: "session.next.shell.started",
+      properties: {
+        sessionID: "session-1",
+        timestamp: 1,
+        callID: "call-1",
+        command: "pwd",
+      },
+    })
+
+    expect(started.commits).toEqual([
+      expect.objectContaining({
+        kind: "tool",
+        phase: "start",
+        partID: "shell:call-1",
+        tool: "bash",
+        shell: {
+          callID: "call-1",
+          command: "pwd",
+        },
+      }),
+    ])
+
+    data = started.data
+    const ended = reduce(data, {
+      type: "session.next.shell.ended",
+      properties: {
+        sessionID: "session-1",
+        timestamp: 2,
+        callID: "call-1",
+        output: "/tmp/demo\n",
+      },
+    })
+
+    expect(ended.commits).toEqual([
+      expect.objectContaining({
+        kind: "tool",
+        phase: "progress",
+        partID: "shell:call-1",
+        tool: "bash",
+        text: "/tmp/demo\n",
+        toolState: "completed",
+        shell: {
+          callID: "call-1",
+          command: "pwd",
+        },
+      }),
+    ])
+  })
+
+  test("suppresses legacy bash part updates once shell events claim the call", () => {
+    let data = reduce(createSessionData(), {
+      type: "session.next.shell.started",
+      properties: {
+        sessionID: "session-1",
+        timestamp: 1,
+        callID: "call-1",
+        command: "pwd",
+      },
+    }).data
+
+    expect(
+      reduce(
+        data,
+        tool({
+          id: "tool-1",
+          messageID: "msg-1",
+          callID: "call-1",
+          tool: "bash",
+          state: {
+            status: "running",
+            input: {
+              command: "pwd",
+            },
+            time: { start: 1 },
+          },
+        }),
+      ).commits,
+    ).toEqual([])
+
+    data = reduce(data, {
+      type: "session.next.shell.ended",
+      properties: {
+        sessionID: "session-1",
+        timestamp: 2,
+        callID: "call-1",
+        output: "/tmp/demo\n",
+      },
+    }).data
+
+    expect(
+      reduce(
+        data,
+        tool({
+          id: "tool-1",
+          messageID: "msg-1",
+          callID: "call-1",
+          tool: "bash",
+          state: {
+            status: "completed",
+            input: {
+              command: "pwd",
+            },
+            output: "/tmp/demo\n",
+            title: "",
+            metadata: {
+              output: "/tmp/demo\n",
+              description: "",
+            },
+            time: { start: 1, end: 2 },
+          },
+        }),
+      ).commits,
+    ).toEqual([])
+  })
+
+  test("suppresses shell events when the legacy bash part claimed the call first", () => {
+    let data = reduce(
+      createSessionData(),
+      tool({
+        id: "tool-1",
+        messageID: "msg-1",
+        callID: "call-1",
+        tool: "bash",
+        state: {
+          status: "running",
+          input: {
+            command: "pwd",
+          },
+          time: { start: 1 },
+        },
+      }),
+    ).data
+
+    expect(
+      reduce(data, {
+        type: "session.next.shell.started",
+        properties: {
+          sessionID: "session-1",
+          timestamp: 1,
+          callID: "call-1",
+          command: "pwd",
+        },
+      }).commits,
+    ).toEqual([])
+
+    data = reduce(
+      data,
+      tool({
+        id: "tool-1",
+        messageID: "msg-1",
+        callID: "call-1",
+        tool: "bash",
+        state: {
+          status: "completed",
+          input: {
+            command: "pwd",
+          },
+          output: "/tmp/demo\n",
+          title: "",
+          metadata: {
+            output: "/tmp/demo\n",
+            description: "",
+          },
+          time: { start: 1, end: 2 },
+        },
+      }),
+    ).data
+
+    expect(
+      reduce(data, {
+        type: "session.next.shell.ended",
+        properties: {
+          sessionID: "session-1",
+          timestamp: 2,
+          callID: "call-1",
+          output: "/tmp/demo\n",
+        },
+      }).commits,
+    ).toEqual([])
+  })
+
+  test("synthesizes a glob start before an error when the running update is missed", () => {
+    expect(
+      reduce(
+        createSessionData(),
+        tool({
+          id: "tool-1",
+          messageID: "msg-1",
+          tool: "glob",
+          state: {
+            status: "error",
+            input: {
+              pattern: "**/*tool*",
+              path: "/tmp/demo/run",
+            },
+            error: "No such file or directory: '/tmp/demo/run'",
+          },
+        }),
+      ).commits,
+    ).toEqual([
+      expect.objectContaining({
+        kind: "tool",
+        tool: "glob",
+        phase: "start",
+        partID: "tool-1",
+        text: "running glob",
+        toolState: "running",
+      }),
+      expect.objectContaining({
+        kind: "tool",
+        tool: "glob",
+        phase: "final",
+        partID: "tool-1",
+        text: "No such file or directory: '/tmp/demo/run'",
+        toolState: "error",
+        toolError: "No such file or directory: '/tmp/demo/run'",
+      }),
+    ])
+  })
+
+  test("flushInterrupted emits one interrupted final per live part", () => {
+    const data = reduce(
+      createSessionData(),
+      text({
+        id: "txt-1",
+        messageID: "msg-1",
+        text: "unfinished",
+      }),
+    ).data
+
+    const first: StreamCommit[] = []
+    flushInterrupted(data, first)
+    expect(first).toEqual([
+      expect.objectContaining({ kind: "assistant", text: "unfinished", phase: "progress" }),
+      expect.objectContaining({ kind: "assistant", phase: "final", interrupted: true }),
+    ])
+
+    const next: StreamCommit[] = []
+    flushInterrupted(data, next)
+    expect(next).toEqual([])
+  })
+
+  test("surfaces session errors as error commits", () => {
+    const out = reduce(createSessionData(), {
+      type: "session.error",
+      properties: {
+        sessionID: "session-1",
+        error: {
+          name: "UnknownError",
+          data: {
+            message: "permission denied",
+          },
+        },
+      },
+    })
+
+    expect(out.commits).toEqual([
+      expect.objectContaining({
+        kind: "error",
+        text: "permission denied",
+      }),
+    ])
+  })
+})

packages/opencode/test/cli/run/session-replay.test.ts

@@ -0,0 +1,692 @@
+import { describe, expect, test } from "bun:test"
+import { replayLocalRows, replaySession } from "@/cli/cmd/run/session-replay"
+import type { SessionMessages } from "@/cli/cmd/run/session.shared"
+import type { RunProvider } from "@/cli/cmd/run/types"
+
+function userMessage(id: string, text: string): SessionMessages[number] {
+  return {
+    info: {
+      id,
+      sessionID: "session-1",
+      role: "user",
+      time: {
+        created: 1,
+      },
+      agent: "build",
+      model: {
+        providerID: "openai",
+        modelID: "gpt-5",
+      },
+    },
+    parts: [
+      {
+        id: `${id}-text`,
+        sessionID: "session-1",
+        messageID: id,
+        type: "text",
+        text,
+      },
+    ],
+  }
+}
+
+function assistantInfo(
+  id: string,
+  input: {
+    parentID?: string
+    modelID?: string
+    providerID?: string
+    time?: { created: number; completed?: number }
+  } = {},
+) {
+  return {
+    id,
+    sessionID: "session-1",
+    role: "assistant" as const,
+    time: input.time ?? { created: 2 },
+    parentID: input.parentID ?? "msg-user-1",
+    modelID: input.modelID ?? "gpt-5",
+    providerID: input.providerID ?? "openai",
+    mode: "chat",
+    agent: "build",
+    path: {
+      cwd: "/tmp",
+      root: "/tmp",
+    },
+    cost: 0,
+    tokens: {
+      input: 1,
+      output: 1,
+      reasoning: 0,
+      cache: {
+        read: 0,
+        write: 0,
+      },
+    },
+  }
+}
+
+function assistantMessage(
+  id: string,
+  text: string,
+  input: {
+    parentID?: string
+    modelID?: string
+    providerID?: string
+    time?: { created: number; completed?: number }
+  } = {},
+): SessionMessages[number] {
+  const time = input.time ?? {
+    created: 200,
+    completed: 3000,
+  }
+
+  return {
+    info: assistantInfo(id, {
+      ...input,
+      time,
+    }),
+    parts: [
+      {
+        id: `${id}-text`,
+        sessionID: "session-1",
+        messageID: id,
+        type: "text",
+        text,
+        time: {
+          start: time.created,
+          end: time.completed,
+        },
+      },
+    ],
+  }
+}
+
+const provider = (name: string): RunProvider => ({
+  id: "openai",
+  name: "OpenAI",
+  source: "api",
+  env: [],
+  options: {},
+  models: {
+    "gpt-5": {
+      id: "gpt-5",
+      providerID: "openai",
+      api: {
+        id: "openai",
+        url: "https://openai.test",
+        npm: "@ai-sdk/openai",
+      },
+      name,
+      capabilities: {
+        temperature: true,
+        reasoning: true,
+        attachment: true,
+        toolcall: true,
+        input: {
+          text: true,
+          audio: false,
+          image: false,
+          video: false,
+          pdf: false,
+        },
+        output: {
+          text: true,
+          audio: false,
+          image: false,
+          video: false,
+          pdf: false,
+        },
+        interleaved: false,
+      },
+      cost: {
+        input: 0,
+        output: 0,
+        cache: {
+          read: 0,
+          write: 0,
+        },
+      },
+      limit: {
+        context: 128000,
+        output: 8192,
+      },
+      status: "active",
+      options: {},
+      headers: {},
+      release_date: "2026-01-01",
+    },
+  },
+})
+
+function runningToolMessage(id: string): SessionMessages[number] {
+  return {
+    info: assistantInfo(id),
+    parts: [
+      {
+        id: `${id}-tool`,
+        sessionID: "session-1",
+        messageID: id,
+        type: "tool",
+        callID: `${id}-call`,
+        tool: "bash",
+        state: {
+          status: "running",
+          input: {
+            command: "pwd",
+          },
+          time: {
+            start: 2,
+          },
+        },
+      },
+    ],
+  }
+}
+
+function shellUserMessage(id: string): SessionMessages[number] {
+  return {
+    info: {
+      id,
+      sessionID: "session-1",
+      role: "user",
+      time: {
+        created: 1,
+      },
+      agent: "build",
+      model: {
+        providerID: "openai",
+        modelID: "gpt-5",
+      },
+    },
+    parts: [
+      {
+        id: `${id}-text`,
+        sessionID: "session-1",
+        messageID: id,
+        type: "text",
+        text: "The following tool was executed by the user",
+        synthetic: true,
+      },
+    ],
+  }
+}
+
+function shellAssistantMessage(id: string, parentID: string): SessionMessages[number] {
+  return {
+    info: assistantInfo(id, {
+      parentID,
+      time: {
+        created: 200,
+        completed: 3000,
+      },
+    }),
+    parts: [
+      {
+        id: `${id}-tool`,
+        sessionID: "session-1",
+        messageID: id,
+        type: "tool",
+        callID: `${id}-call`,
+        tool: "bash",
+        state: {
+          status: "completed",
+          input: {
+            command: "ls",
+          },
+          output: "account.ts\n",
+          title: "",
+          metadata: {
+            output: "account.ts\n",
+            description: "",
+          },
+          time: {
+            start: 200,
+            end: 3000,
+          },
+        },
+      },
+    ],
+  }
+}
+
+describe("run session replay", () => {
+  test("replays persisted user, assistant, and turn summary history into scrollback commits", () => {
+    const out = replaySession({
+      messages: [
+        userMessage("msg-user-1", "Hello, whats the weather today?"),
+        assistantMessage("msg-1", "What city or ZIP code should I check?"),
+      ],
+      permissions: [],
+      questions: [],
+      thinking: true,
+      limits: {},
+    })
+
+    expect(out.commits).toEqual([
+      expect.objectContaining({
+        kind: "user",
+        text: "Hello, whats the weather today?",
+        phase: "start",
+        source: "system",
+        messageID: "msg-user-1",
+      }),
+      expect.objectContaining({
+        kind: "assistant",
+        text: "What city or ZIP code should I check?",
+        phase: "progress",
+        source: "assistant",
+        messageID: "msg-1",
+      }),
+      expect.objectContaining({
+        kind: "system",
+        text: "▣ Build · gpt-5 · 2.8s",
+        phase: "final",
+        source: "system",
+        messageID: "msg-1",
+        summary: {
+          agent: "Build",
+          model: "gpt-5",
+          duration: "2.8s",
+        },
+      }),
+    ])
+    expect(out.patch).toEqual(
+      expect.objectContaining({
+        phase: "idle",
+        status: "",
+      }),
+    )
+  })
+
+  test("uses provider model names for replayed turn summaries when available", () => {
+    const out = replaySession({
+      messages: [
+        userMessage("msg-user-1", "Hello, whats the weather today?"),
+        assistantMessage("msg-1", "What city or ZIP code should I check?"),
+      ],
+      permissions: [],
+      questions: [],
+      thinking: true,
+      limits: {},
+      providers: [provider("Little Frank")],
+    })
+
+    expect(out.commits.at(-1)).toEqual(
+      expect.objectContaining({
+        kind: "system",
+        text: "▣ Build · Little Frank · 2.8s",
+        summary: {
+          agent: "Build",
+          model: "Little Frank",
+          duration: "2.8s",
+        },
+      }),
+    )
+  })
+
+  test("replays one turn summary for the final assistant in a multi-step turn", () => {
+    const out = replaySession({
+      messages: [
+        userMessage("msg-user-1", "Plan and then answer"),
+        assistantMessage("msg-step-1", "Working", {
+          parentID: "msg-user-1",
+          time: { created: 200, completed: 900 },
+        }),
+        assistantMessage("msg-step-2", "Done", {
+          parentID: "msg-user-1",
+          time: { created: 1000, completed: 3000 },
+        }),
+      ],
+      permissions: [],
+      questions: [],
+      thinking: true,
+      limits: {},
+    })
+
+    expect(out.commits.filter((commit) => commit.summary)).toEqual([
+      expect.objectContaining({
+        kind: "system",
+        text: "▣ Build · gpt-5 · 2.0s",
+        messageID: "msg-step-2",
+      }),
+    ])
+  })
+
+  test("keeps the footer in a running state for resumed active tools", () => {
+    const out = replaySession({
+      messages: [runningToolMessage("msg-1")],
+      permissions: [],
+      questions: [],
+      thinking: true,
+      limits: {},
+    })
+
+    expect(out.patch).toEqual(
+      expect.objectContaining({
+        phase: "running",
+        status: "running bash",
+      }),
+    )
+  })
+
+  test("does not replay turn summaries for shell-mode commands", () => {
+    const out = replaySession({
+      messages: [
+        shellUserMessage("msg-shell-user-1"),
+        shellAssistantMessage("msg-shell-assistant-1", "msg-shell-user-1"),
+      ],
+      permissions: [],
+      questions: [],
+      thinking: true,
+      limits: {},
+    })
+
+    expect(out.commits.some((commit) => commit.summary)).toBe(false)
+    expect(out.commits).toContainEqual(
+      expect.objectContaining({
+        kind: "tool",
+        text: "account.ts\n",
+        tool: "bash",
+        toolState: "completed",
+      }),
+    )
+  })
+
+  test("merges failed local rows ahead of later persisted prompts", () => {
+    const persisted = {
+      kind: "user",
+      text: "successful",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-2",
+    } as const
+    const failed = {
+      kind: "user",
+      text: "failed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "network unavailable",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+
+    expect(
+      replayLocalRows([userMessage("msg-user-2", "successful")], [persisted], [{ commit: failed }, { commit: error }]),
+    ).toEqual([failed, error, persisted])
+  })
+
+  test("retains local errors but not duplicate local prompts once a prompt persists", () => {
+    const persisted = {
+      kind: "user",
+      text: "failed after persistence",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "connection closed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [userMessage("msg-user-1", "failed after persistence")],
+        [persisted],
+        [{ commit: persisted }, { commit: error }],
+      ),
+    ).toEqual([persisted, error])
+  })
+
+  test("keeps a local turn failure below assistant output already visible for that turn", () => {
+    const first = {
+      kind: "user",
+      text: "start",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const answer = {
+      kind: "assistant",
+      text: "partial answer",
+      phase: "progress",
+      source: "assistant",
+      messageID: "msg-assistant-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "stream failed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const second = {
+      kind: "user",
+      text: "retry",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-2",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [userMessage("msg-user-1", "start"), userMessage("msg-user-2", "retry")],
+        [first, answer, second],
+        [
+          {
+            commit: error,
+            after: { kind: "assistant", text: "partial answer", phase: "progress", messageID: "msg-assistant-1" },
+          },
+        ],
+      ),
+    ).toEqual([first, answer, error, second])
+  })
+
+  test("keeps a local failure above assistant output received after the failure", () => {
+    const first = {
+      kind: "user",
+      text: "start",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "request failed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const late = {
+      kind: "assistant",
+      text: "late answer",
+      phase: "progress",
+      source: "assistant",
+      messageID: "msg-assistant-1",
+    } as const
+
+    expect(replayLocalRows([userMessage("msg-user-1", "start")], [first, late], [{ commit: error }])).toEqual([
+      first,
+      error,
+      late,
+    ])
+  })
+
+  test("inserts a local failure between persisted output chunks spanning that failure", () => {
+    const first = {
+      kind: "user",
+      text: "start",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const complete = {
+      kind: "assistant",
+      text: "before after",
+      phase: "progress",
+      source: "assistant",
+      messageID: "msg-assistant-1",
+      partID: "part-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "stream failed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [userMessage("msg-user-1", "start")],
+        [first, complete],
+        [
+          {
+            commit: error,
+            after: {
+              kind: "assistant",
+              text: "before ",
+              phase: "progress",
+              messageID: "msg-assistant-1",
+              partID: "part-1",
+              visible: "before ",
+            },
+          },
+        ],
+      ),
+    ).toEqual([first, { ...complete, text: "before " }, error, { ...complete, text: "after" }])
+  })
+
+  test("places an unpersisted failed prompt before live output from that turn", () => {
+    const prompt = {
+      kind: "user",
+      text: "start",
+      phase: "start",
+      source: "system",
+      messageID: "msg-1",
+    } as const
+    const answer = {
+      kind: "assistant",
+      text: "partial answer",
+      phase: "progress",
+      source: "assistant",
+      messageID: "msg-2",
+    } as const
+    const error = {
+      kind: "error",
+      text: "stream failed",
+      phase: "start",
+      source: "system",
+      messageID: "msg-1",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [],
+        [answer],
+        [
+          { commit: prompt },
+          {
+            commit: error,
+            after: { kind: "assistant", text: "partial answer", phase: "progress", messageID: "msg-2" },
+          },
+        ],
+      ),
+    ).toEqual([prompt, answer, error])
+  })
+
+  test("anchors a failure after the visible start of a tool that later completes", () => {
+    const prompt = {
+      kind: "user",
+      text: "run ls",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const running = {
+      kind: "tool",
+      text: "running bash",
+      phase: "start",
+      source: "tool",
+      messageID: "msg-assistant-1",
+      partID: "part-tool-1",
+      toolState: "running",
+    } as const
+    const completed = {
+      kind: "tool",
+      text: "file.txt",
+      phase: "final",
+      source: "tool",
+      messageID: "msg-assistant-1",
+      partID: "part-tool-1",
+      toolState: "completed",
+    } as const
+    const error = {
+      kind: "error",
+      text: "connection lost",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [userMessage("msg-user-1", "run ls")],
+        [prompt, running, completed],
+        [
+          {
+            commit: error,
+            after: {
+              kind: "tool",
+              text: "running bash",
+              phase: "start",
+              messageID: "msg-assistant-1",
+              partID: "part-tool-1",
+              toolState: "running",
+            },
+          },
+        ],
+      ),
+    ).toEqual([prompt, running, error, completed])
+  })
+
+  test("retains an unpersisted local diagnostic before later persisted prompts", () => {
+    const first = {
+      kind: "user",
+      text: "before",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-1",
+    } as const
+    const error = {
+      kind: "error",
+      text: "failed to start new session",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-2",
+    } as const
+    const second = {
+      kind: "user",
+      text: "after",
+      phase: "start",
+      source: "system",
+      messageID: "msg-user-3",
+    } as const
+
+    expect(
+      replayLocalRows(
+        [userMessage("msg-user-1", "before"), userMessage("msg-user-3", "after")],
+        [first, second],
+        [{ commit: error }],
+      ),
+    ).toEqual([first, error, second])
+  })
+})

packages/opencode/test/cli/run/session.shared.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test"
+import {
+  createSession,
+  sessionHistory,
+  sessionVariant,
+  type RunSession,
+  type SessionMessages,
+} from "@/cli/cmd/run/session.shared"
+
+type Message = SessionMessages[number]
+type Part = Message["parts"][number]
+type TextPart = Extract<Part, { type: "text" }>
+type AgentPart = Extract<Part, { type: "agent" }>
+type FilePart = Extract<Part, { type: "file" }>
+
+const model = {
+  providerID: "openai",
+  modelID: "gpt-5",
+}
+
+function userMessage(id: string, parts: Message["parts"], variant = "high"): Message {
+  return {
+    info: {
+      id,
+      sessionID: "session-1",
+      role: "user",
+      time: {
+        created: 1,
+      },
+      agent: "build",
+      model: {
+        ...model,
+        variant,
+      },
+    },
+    parts,
+  }
+}
+
+function assistantMessage(id: string, parts: Message["parts"]): Message {
+  return {
+    info: {
+      id,
+      sessionID: "session-1",
+      role: "assistant",
+      time: {
+        created: 1,
+      },
+      parentID: "msg-user-1",
+      modelID: "gpt-5",
+      providerID: "openai",
+      mode: "chat",
+      agent: "build",
+      path: {
+        cwd: "/tmp",
+        root: "/tmp",
+      },
+      cost: 0,
+      tokens: {
+        input: 1,
+        output: 1,
+        reasoning: 0,
+        cache: {
+          read: 0,
+          write: 0,
+        },
+      },
+    },
+    parts,
+  }
+}
+
+function textPart(id: string, messageID: string, text: string, input: Partial<TextPart> = {}): TextPart {
+  return {
+    id,
+    sessionID: "session-1",
+    messageID,
+    type: "text",
+    text,
+    synthetic: input.synthetic,
+  }
+}
+
+function agentPart(id: string, messageID: string, name: string, source?: AgentPart["source"]): AgentPart {
+  return {
+    id,
+    sessionID: "session-1",
+    messageID,
+    type: "agent",
+    name,
+    source,
+  }
+}
+
+function filePart(id: string, messageID: string, url: string, input: Partial<FilePart> = {}): FilePart {
+  return {
+    id,
+    sessionID: "session-1",
+    messageID,
+    type: "file",
+    mime: input.mime ?? "text/plain",
+    filename: input.filename,
+    url,
+    source: input.source,
+  }
+}
+
+describe("run session shared", () => {
+  test("builds user prompt text from text, file, and agent parts", () => {
+    const msgs: SessionMessages = [
+      assistantMessage("msg-assistant-1", [textPart("txt-assistant-1", "msg-assistant-1", "ignore me")]),
+      userMessage("msg-user-1", [
+        textPart("txt-user-1", "msg-user-1", "look @scan"),
+        textPart("txt-user-2", "msg-user-1", "hidden", { synthetic: true }),
+        agentPart("agent-user-1", "msg-user-1", "scan", {
+          start: 5,
+          end: 10,
+          value: "@scan",
+        }),
+        filePart("file-user-1", "msg-user-1", "file:///tmp/note.ts"),
+      ]),
+    ]
+
+    const out = createSession(msgs)
+    expect(out.first).toBe(false)
+    expect(out.turns).toHaveLength(1)
+    expect(out.turns[0]?.prompt.text).toBe("look @scan @note.ts")
+    expect(out.turns[0]?.prompt.parts).toEqual([
+      {
+        type: "agent",
+        name: "scan",
+        source: {
+          start: 5,
+          end: 10,
+          value: "@scan",
+        },
+      },
+      {
+        type: "file",
+        mime: "text/plain",
+        filename: undefined,
+        url: "file:///tmp/note.ts",
+        source: {
+          type: "file",
+          path: "file:///tmp/note.ts",
+          text: {
+            start: 11,
+            end: 19,
+            value: "@note.ts",
+          },
+        },
+      },
+    ])
+  })
+
+  test("reuses existing mentions when file and agent parts have no source", () => {
+    const out = createSession([
+      userMessage("msg-user-1", [
+        textPart("txt-user-1", "msg-user-1", "look @scan @note.ts"),
+        agentPart("agent-user-1", "msg-user-1", "scan"),
+        filePart("file-user-1", "msg-user-1", "file:///tmp/note.ts"),
+      ]),
+    ])
+
+    expect(out.turns[0]?.prompt).toEqual({
+      text: "look @scan @note.ts",
+      parts: [
+        {
+          type: "agent",
+          name: "scan",
+          source: {
+            start: 5,
+            end: 10,
+            value: "@scan",
+          },
+        },
+        {
+          type: "file",
+          mime: "text/plain",
+          filename: undefined,
+          url: "file:///tmp/note.ts",
+          source: {
+            type: "file",
+            path: "file:///tmp/note.ts",
+            text: {
+              start: 11,
+              end: 19,
+              value: "@note.ts",
+            },
+          },
+        },
+      ],
+    })
+  })
+
+  test("dedupes consecutive history entries, drops blanks, and copies prompt parts", () => {
+    const parts = [
+      {
+        type: "agent" as const,
+        name: "scan",
+        source: {
+          start: 0,
+          end: 5,
+          value: "@scan",
+        },
+      },
+    ]
+    const session: RunSession = {
+      first: false,
+      turns: [
+        { prompt: { text: "one", parts }, provider: "openai", model: "gpt-5", variant: "high" },
+        { prompt: { text: "one", parts: structuredClone(parts) }, provider: "openai", model: "gpt-5", variant: "high" },
+        { prompt: { text: "   ", parts: [] }, provider: "openai", model: "gpt-5", variant: "high" },
+        { prompt: { text: "two", parts: [] }, provider: "openai", model: "gpt-5", variant: undefined },
+      ],
+    }
+
+    const out = sessionHistory(session)
+
+    expect(out.map((item) => item.text)).toEqual(["one", "two"])
+    expect(out[0]?.parts).toEqual(parts)
+    expect(out[0]?.parts).not.toBe(parts)
+    expect(out[0]?.parts[0]).not.toBe(parts[0])
+  })
+
+  test("returns the latest matching variant for the active model", () => {
+    const session: RunSession = {
+      first: false,
+      turns: [
+        { prompt: { text: "one", parts: [] }, provider: "openai", model: "gpt-5", variant: "high" },
+        { prompt: { text: "two", parts: [] }, provider: "anthropic", model: "sonnet", variant: "max" },
+        { prompt: { text: "three", parts: [] }, provider: "openai", model: "gpt-5", variant: undefined },
+      ],
+    }
+
+    expect(sessionVariant(session, model)).toBeUndefined()
+
+    session.turns.push({
+      prompt: { text: "four", parts: [] },
+      provider: "openai",
+      model: "gpt-5",
+      variant: "minimal",
+    })
+
+    expect(sessionVariant(session, model)).toBe("minimal")
+  })
+})

packages/opencode/test/cli/run/stream.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test"
+import { writeSessionOutput } from "@/cli/cmd/run/stream"
+import type { FooterApi, FooterEvent, StreamCommit } from "@/cli/cmd/run/types"
+
+function footer() {
+  const events: FooterEvent[] = []
+  const commits: StreamCommit[] = []
+
+  const api: FooterApi = {
+    isClosed: false,
+    onPrompt: () => () => {},
+    onQueuedRemove: () => () => {},
+    onClose: () => () => {},
+    event: (next) => {
+      events.push(next)
+    },
+    append: (next) => {
+      commits.push(next)
+    },
+    idle: () => Promise.resolve(),
+    close: () => {},
+    destroy: () => {},
+  }
+
+  return { api, events, commits }
+}
+
+describe("run stream bridge", () => {
+  test("defaults status patches to running phase", () => {
+    const out = footer()
+
+    writeSessionOutput(
+      {
+        footer: out.api,
+      },
+      {
+        commits: [],
+        footer: {
+          patch: {
+            status: "assistant responding",
+          },
+        },
+      },
+    )
+
+    expect(out.events).toEqual([
+      {
+        type: "stream.patch",
+        patch: {
+          phase: "running",
+          status: "assistant responding",
+        },
+      },
+    ])
+  })
+})

packages/opencode/test/cli/run/subagent-data.test.ts

@@ -0,0 +1,547 @@
+import { describe, expect, test } from "bun:test"
+import type { Event } from "@opencode-ai/sdk/v2"
+import { entryBody } from "@/cli/cmd/run/entry.body"
+import {
+  bootstrapSubagentCalls,
+  bootstrapSubagentData,
+  createSubagentData,
+  reduceSubagentData,
+  snapshotSubagentData,
+} from "@/cli/cmd/run/subagent-data"
+
+type SessionMessage = Parameters<typeof bootstrapSubagentData>[0]["messages"][number]
+type ChildMessage = Parameters<typeof bootstrapSubagentCalls>[0]["messages"][number]
+
+function visible(commits: Array<Parameters<typeof entryBody>[0]>) {
+  return commits.flatMap((item) => {
+    const body = entryBody(item)
+    if (body.type === "none") {
+      return []
+    }
+
+    if (body.type === "structured") {
+      if (body.snapshot.kind === "code" || body.snapshot.kind === "task") {
+        return [body.snapshot.title]
+      }
+
+      if (body.snapshot.kind === "diff") {
+        return body.snapshot.items.map((item) => item.title)
+      }
+
+      if (body.snapshot.kind === "todo") {
+        return ["# Todos"]
+      }
+
+      return ["# Questions"]
+    }
+
+    return [body.content]
+  })
+}
+
+function reduce(data: ReturnType<typeof createSubagentData>, event: unknown) {
+  return reduceSubagentData({
+    data,
+    event: event as Event,
+    sessionID: "parent-1",
+    thinking: true,
+    limits: {},
+  })
+}
+
+function taskMessage(sessionID: string, status: "running" | "completed" | "interrupted" = "completed"): SessionMessage {
+  if (status === "running") {
+    return {
+      parts: [
+        {
+          id: `part-${sessionID}`,
+          sessionID: "parent-1",
+          messageID: `msg-${sessionID}`,
+          type: "tool",
+          callID: `call-${sessionID}`,
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              description: "Scan reducer paths",
+              subagent_type: "explore",
+            },
+            title: "Reducer touchpoints",
+            metadata: {
+              sessionId: sessionID,
+              toolcalls: 4,
+            },
+            time: { start: 1 },
+          },
+        },
+      ],
+    }
+  }
+
+  if (status === "interrupted") {
+    return {
+      parts: [
+        {
+          id: `part-${sessionID}`,
+          sessionID: "parent-1",
+          messageID: `msg-${sessionID}`,
+          type: "tool",
+          callID: `call-${sessionID}`,
+          tool: "task",
+          state: {
+            status: "error",
+            input: {
+              description: "Scan reducer paths",
+              subagent_type: "explore",
+            },
+            error: "Tool execution aborted",
+            metadata: {
+              sessionId: sessionID,
+              toolcalls: 4,
+              interrupted: true,
+            },
+            time: { start: 1, end: 2 },
+          },
+        },
+      ],
+    }
+  }
+
+  return {
+    parts: [
+      {
+        id: `part-${sessionID}`,
+        sessionID: "parent-1",
+        messageID: `msg-${sessionID}`,
+        type: "tool",
+        callID: `call-${sessionID}`,
+        tool: "task",
+        state: {
+          status: "completed",
+          input: {
+            description: "Scan reducer paths",
+            subagent_type: "explore",
+          },
+          output: "",
+          title: "Reducer touchpoints",
+          metadata: {
+            sessionId: sessionID,
+            toolcalls: 4,
+          },
+          time: { start: 1, end: 2 },
+        },
+      },
+    ],
+  }
+}
+
+function question(id: string, sessionID: string) {
+  return {
+    id,
+    sessionID,
+    questions: [
+      {
+        question: "Mode?",
+        header: "Mode",
+        options: [{ label: "Fast", description: "Quick pass" }],
+        multiple: false,
+      },
+    ],
+  }
+}
+
+function childMessage(input: {
+  messageID: string
+  sessionID: string
+  role: "user" | "assistant"
+  parts: ChildMessage["parts"]
+}) {
+  if (input.role === "user") {
+    return {
+      info: {
+        id: input.messageID,
+        sessionID: input.sessionID,
+        role: "user",
+        time: {
+          created: 1,
+        },
+        agent: "test",
+        model: {
+          providerID: "openai",
+          modelID: "gpt-5",
+        },
+      },
+      parts: input.parts,
+    } satisfies ChildMessage
+  }
+
+  return {
+    info: {
+      id: input.messageID,
+      sessionID: input.sessionID,
+      role: "assistant",
+      time: {
+        created: 2,
+        completed: 3,
+      },
+      parentID: "msg-user-1",
+      providerID: "openai",
+      modelID: "gpt-5",
+      mode: "default",
+      agent: "explore",
+      path: {
+        cwd: "/tmp",
+        root: "/tmp",
+      },
+      cost: 0,
+      tokens: {
+        input: 1,
+        output: 1,
+        reasoning: 0,
+        cache: {
+          read: 0,
+          write: 0,
+        },
+      },
+      finish: "stop",
+    },
+    parts: input.parts,
+  } satisfies ChildMessage
+}
+
+describe("run subagent data", () => {
+  test("bootstraps tabs and child blockers from parent task parts", () => {
+    const data = createSubagentData()
+
+    expect(
+      bootstrapSubagentData({
+        data,
+        messages: [taskMessage("child-1")],
+        children: [{ id: "child-1" }, { id: "child-2" }],
+        permissions: [
+          {
+            id: "perm-1",
+            sessionID: "child-1",
+            permission: "read",
+            patterns: ["src/**/*.ts"],
+            metadata: {},
+            always: [],
+          },
+          {
+            id: "perm-2",
+            sessionID: "other",
+            permission: "read",
+            patterns: ["src/**/*.ts"],
+            metadata: {},
+            always: [],
+          },
+        ],
+        questions: [question("question-1", "child-1"), question("question-2", "other")],
+      }),
+    ).toBe(true)
+
+    const snapshot = snapshotSubagentData(data)
+
+    expect(snapshot.tabs).toEqual([
+      expect.objectContaining({
+        sessionID: "child-1",
+        label: "Explore",
+        description: "Scan reducer paths",
+        title: "Reducer touchpoints",
+        status: "completed",
+        toolCalls: 4,
+      }),
+    ])
+    expect(snapshot.details).toEqual({
+      "child-1": {
+        sessionID: "child-1",
+        commits: [],
+      },
+    })
+    expect(snapshot.permissions.map((item) => item.id)).toEqual(["perm-1"])
+    expect(snapshot.questions.map((item) => item.id)).toEqual(["question-1"])
+  })
+
+  test("marks interrupted task tabs as cancelled during bootstrap", () => {
+    const data = createSubagentData()
+
+    bootstrapSubagentData({
+      data,
+      messages: [taskMessage("child-1", "interrupted")],
+      children: [{ id: "child-1" }],
+      permissions: [],
+      questions: [],
+    })
+
+    expect(snapshotSubagentData(data).tabs).toEqual([
+      expect.objectContaining({
+        sessionID: "child-1",
+        status: "cancelled",
+      }),
+    ])
+  })
+
+  test("captures child activity and blocker metadata in the footer detail state", () => {
+    const data = createSubagentData()
+
+    bootstrapSubagentData({
+      data,
+      messages: [taskMessage("child-1", "running")],
+      children: [{ id: "child-1" }],
+      permissions: [],
+      questions: [],
+    })
+
+    reduce(data, {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "txt-user-1",
+          messageID: "msg-user-1",
+          sessionID: "child-1",
+          type: "text",
+          text: "Inspect footer tabs",
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.updated",
+      properties: {
+        sessionID: "child-1",
+        info: {
+          id: "msg-user-1",
+          role: "user",
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.updated",
+      properties: {
+        sessionID: "child-1",
+        info: {
+          id: "msg-assistant-1",
+          role: "assistant",
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "reason-1",
+          messageID: "msg-assistant-1",
+          sessionID: "child-1",
+          type: "reasoning",
+          text: "planning next steps",
+          time: { start: 1 },
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool-1",
+          messageID: "msg-assistant-1",
+          sessionID: "child-1",
+          type: "tool",
+          callID: "call-1",
+          tool: "bash",
+          state: {
+            status: "running",
+            input: {
+              command: "git status --short",
+            },
+            time: { start: 1 },
+          },
+        },
+      },
+    })
+    reduce(data, {
+      type: "permission.asked",
+      properties: {
+        id: "perm-1",
+        sessionID: "child-1",
+        permission: "bash",
+        patterns: ["git status --short"],
+        metadata: {},
+        always: [],
+        tool: {
+          messageID: "msg-assistant-1",
+          callID: "call-1",
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "txt-1",
+          messageID: "msg-assistant-1",
+          sessionID: "child-1",
+          type: "text",
+          text: "hello",
+        },
+      },
+    })
+    reduce(data, {
+      type: "message.part.delta",
+      properties: {
+        sessionID: "child-1",
+        messageID: "msg-assistant-1",
+        partID: "txt-1",
+        field: "text",
+        delta: " world",
+      },
+    })
+
+    const snapshot = snapshotSubagentData(data)
+
+    expect(snapshot.tabs).toEqual([expect.objectContaining({ sessionID: "child-1", status: "running" })])
+    expect(visible(snapshot.details["child-1"]?.commits ?? [])).toEqual([
+      "› Inspect footer tabs",
+      "_Thinking:_ planning next steps",
+      "$ git status --short",
+      "hello world",
+    ])
+    expect(snapshot.permissions).toEqual([
+      expect.objectContaining({
+        id: "perm-1",
+        metadata: {
+          input: {
+            command: "git status --short",
+          },
+        },
+      }),
+    ])
+    expect(snapshot.questions).toEqual([])
+  })
+
+  test("replays bootstrapped child session messages into inspector commits", () => {
+    const data = createSubagentData()
+
+    bootstrapSubagentData({
+      data,
+      messages: [taskMessage("child-1", "completed")],
+      children: [{ id: "child-1" }],
+      permissions: [],
+      questions: [],
+    })
+
+    expect(
+      bootstrapSubagentCalls({
+        data,
+        sessionID: "child-1",
+        messages: [
+          childMessage({
+            messageID: "msg-user-1",
+            sessionID: "child-1",
+            role: "user",
+            parts: [
+              {
+                id: "txt-user-1",
+                messageID: "msg-user-1",
+                sessionID: "child-1",
+                type: "text",
+                text: "Inspect footer tabs",
+                time: { start: 1, end: 1 },
+              },
+            ],
+          }),
+          childMessage({
+            messageID: "msg-assistant-1",
+            sessionID: "child-1",
+            role: "assistant",
+            parts: [
+              {
+                id: "reason-1",
+                messageID: "msg-assistant-1",
+                sessionID: "child-1",
+                type: "reasoning",
+                text: "planning next steps",
+                time: { start: 2, end: 2 },
+              },
+              {
+                id: "txt-1",
+                messageID: "msg-assistant-1",
+                sessionID: "child-1",
+                type: "text",
+                text: "hello world",
+                time: { start: 2, end: 3 },
+              },
+            ],
+          }),
+        ],
+        thinking: true,
+        limits: {},
+      }),
+    ).toBe(true)
+
+    expect(visible(snapshotSubagentData(data).details["child-1"]?.commits ?? [])).toEqual([
+      "› Inspect footer tabs",
+      "_Thinking:_ planning next steps",
+      "hello world",
+    ])
+  })
+
+  test("marks a running tab cancelled when the child session aborts", () => {
+    const data = createSubagentData()
+
+    bootstrapSubagentData({
+      data,
+      messages: [taskMessage("child-1", "running")],
+      children: [{ id: "child-1" }],
+      permissions: [],
+      questions: [],
+    })
+
+    reduce(data, {
+      type: "message.updated",
+      properties: {
+        sessionID: "child-1",
+        info: {
+          id: "msg-assistant-1",
+          sessionID: "child-1",
+          role: "assistant",
+          time: {
+            created: 1,
+            completed: 2,
+          },
+          error: {
+            name: "MessageAbortedError",
+            data: {
+              message: "Aborted",
+            },
+          },
+          parentID: "msg-user-1",
+          providerID: "openai",
+          modelID: "gpt-5",
+          mode: "default",
+          agent: "explore",
+          path: {
+            cwd: "/tmp",
+            root: "/tmp",
+          },
+          cost: 0,
+          tokens: {
+            input: 1,
+            output: 1,
+            reasoning: 0,
+            cache: {
+              read: 0,
+              write: 0,
+            },
+          },
+          finish: "error",
+        },
+      },
+    })
+
+    expect(snapshotSubagentData(data).tabs).toEqual([
+      expect.objectContaining({
+        sessionID: "child-1",
+        status: "cancelled",
+      }),
+    ])
+  })
+})

packages/opencode/test/cli/run/theme.test.ts

@@ -0,0 +1,177 @@
+import { expect, test } from "bun:test"
+import { RGBA, type CliRenderer, type TerminalColors } from "@opentui/core"
+import { RUN_THEME_FALLBACK, generateSystem, resolveRunTheme, resolveTheme } from "@/cli/cmd/run/theme"
+
+const palette = ["#15161e", "#f7768e", "#9ece6a", "#e0af68", "#7aa2f7", "#bb9af7", "#7dcfff", "#c0caf5"] as const
+
+function terminalColors(input: Partial<TerminalColors> = {}): TerminalColors {
+  return {
+    palette: Array.from({ length: 256 }, (_, index) => input.palette?.[index] ?? palette[index % palette.length]!),
+    defaultBackground: input.defaultBackground ?? "#1a1b26",
+    defaultForeground: input.defaultForeground ?? "#c0caf5",
+    cursorColor: input.cursorColor ?? "#ff9e64",
+    mouseForeground: input.mouseForeground ?? null,
+    mouseBackground: input.mouseBackground ?? null,
+    tekForeground: input.tekForeground ?? null,
+    tekBackground: input.tekBackground ?? null,
+    highlightBackground: input.highlightBackground ?? "#33467c",
+    highlightForeground: input.highlightForeground ?? "#c0caf5",
+  }
+}
+
+function renderer(
+  input: {
+    themeMode?: "dark" | "light"
+    colors?: TerminalColors
+    fail?: boolean
+  } = {},
+) {
+  return {
+    themeMode: input.themeMode,
+    getPalette: async () => {
+      if (input.fail) {
+        throw new Error("boom")
+      }
+
+      return input.colors ?? terminalColors()
+    },
+  } as CliRenderer
+}
+
+function expectRgba(color: unknown) {
+  expect(color).toBeInstanceOf(RGBA)
+  if (!(color instanceof RGBA)) {
+    throw new Error("expected RGBA")
+  }
+
+  return color
+}
+
+function expectIndexed(color: unknown) {
+  const rgba = expectRgba(color)
+  expect(rgba.intent).toBe("indexed")
+  expect(rgba.slot).toBeLessThan(256)
+}
+
+function spread(color: RGBA) {
+  const [r, g, b] = color.toInts()
+  return Math.max(r, g, b) - Math.min(r, g, b)
+}
+
+test("falls back when palette lookup fails", async () => {
+  expect(await resolveRunTheme(renderer({ fail: true }))).toBe(RUN_THEME_FALLBACK)
+})
+
+test("returns syntax styles and indexed splash colors", async () => {
+  const theme = await resolveRunTheme(renderer({ themeMode: "dark" }))
+
+  try {
+    expect(theme.block.syntax).toBeDefined()
+    expect(theme.block.subtleSyntax).toBeDefined()
+    expect([...theme.block.syntax!.getAllStyles()].length).toBeGreaterThan(0)
+    expect([...theme.block.subtleSyntax!.getAllStyles()].length).toBeGreaterThan(0)
+    expectIndexed(theme.splash.left)
+    expectIndexed(theme.splash.right)
+    expectIndexed(theme.splash.leftShadow)
+    expectIndexed(theme.splash.rightShadow)
+    expectIndexed(theme.block.highlight)
+    expectIndexed(theme.block.warning)
+    expectRgba(theme.footer.highlight)
+    expectRgba(theme.footer.statusAccent)
+    expectRgba(theme.footer.surface)
+    expect(expectRgba(theme.footer.statusAccent).toInts()).not.toEqual(expectRgba(theme.footer.status).toInts())
+  } finally {
+    theme.block.syntax?.destroy()
+    theme.block.subtleSyntax?.destroy()
+  }
+})
+
+test("keeps footer surfaces exact while scrollback stays palette matched", async () => {
+  const colors = terminalColors({
+    defaultBackground: "#0f172a",
+    defaultForeground: "#e2e8f0",
+  })
+  const theme = await resolveRunTheme(renderer({ themeMode: "dark", colors }))
+  const exact = resolveTheme(generateSystem(colors, "dark"), "dark")
+
+  try {
+    expect(expectRgba(theme.footer.selected).toInts()).toEqual(expectRgba(exact.backgroundElement).toInts())
+    expect(expectRgba(theme.footer.border).toInts()).toEqual(expectRgba(exact.border).toInts())
+    expect(expectRgba(theme.footer.pane).toInts()).toEqual(expectRgba(exact.backgroundMenu).toInts())
+    expect(expectRgba(theme.footer.selected).intent).toBe("rgb")
+    expectIndexed(theme.block.highlight)
+    expectIndexed(theme.block.warning)
+  } finally {
+    theme.block.syntax?.destroy()
+    theme.block.subtleSyntax?.destroy()
+  }
+})
+
+test("uses refreshed background brightness when cached renderer mode is stale", async () => {
+  const colors = terminalColors({
+    defaultBackground: "#fbf1c7",
+    defaultForeground: "#3c3836",
+  })
+  const stale = await resolveRunTheme(renderer({ themeMode: "dark", colors }))
+  const light = await resolveRunTheme(renderer({ themeMode: "light", colors }))
+
+  try {
+    expect(expectRgba(stale.footer.surface).toInts()).toEqual(expectRgba(light.footer.surface).toInts())
+  } finally {
+    stale.block.syntax?.destroy()
+    stale.block.subtleSyntax?.destroy()
+    light.block.syntax?.destroy()
+    light.block.subtleSyntax?.destroy()
+  }
+})
+
+test("keeps renderer mode when refreshed default background is unavailable", async () => {
+  const colors = {
+    ...terminalColors(),
+    defaultBackground: null,
+    palette: ["#000000", ...terminalColors().palette.slice(1)],
+  }
+  const light = await resolveRunTheme(renderer({ themeMode: "light", colors }))
+  const dark = await resolveRunTheme(renderer({ themeMode: "dark", colors }))
+
+  try {
+    expect(expectRgba(light.footer.surface).toInts()).not.toEqual(expectRgba(dark.footer.surface).toInts())
+  } finally {
+    light.block.syntax?.destroy()
+    light.block.subtleSyntax?.destroy()
+    dark.block.syntax?.destroy()
+    dark.block.subtleSyntax?.destroy()
+  }
+})
+
+test("keeps dark surfaces neutral on saturated backgrounds", () => {
+  const theme = resolveTheme(
+    generateSystem(
+      terminalColors({
+        defaultBackground: "#0000ff",
+        defaultForeground: "#ffffff",
+      }),
+      "dark",
+    ),
+    "dark",
+  )
+
+  expect(spread(theme.backgroundPanel)).toBeLessThan(10)
+  expect(spread(theme.backgroundElement)).toBeLessThan(10)
+})
+
+test("keeps light surfaces close to neutral on warm backgrounds", () => {
+  const theme = resolveTheme(
+    generateSystem(
+      terminalColors({
+        defaultBackground: "#fbf1c7",
+        defaultForeground: "#3c3836",
+      }),
+      "light",
+    ),
+    "light",
+  )
+
+  expect(spread(theme.backgroundPanel)).toBeLessThan(60)
+  expect(spread(theme.backgroundElement)).toBeLessThan(60)
+})

packages/opencode/test/cli/run/variant.shared.test.ts

@@ -0,0 +1,217 @@
+import path from "path"
+import { NodeFileSystem } from "@effect/platform-node"
+import { FSUtil } from "@opencode-ai/core/fs-util"
+import { describe, expect, test } from "bun:test"
+import { Effect, FileSystem, Layer } from "effect"
+import { Global } from "@opencode-ai/core/global"
+import {
+  createVariantRuntime,
+  cycleVariant,
+  formatModelLabel,
+  pickVariant,
+  resolveVariant,
+} from "@/cli/cmd/run/variant.shared"
+import type { SessionMessages } from "@/cli/cmd/run/session.shared"
+import type { RunProvider } from "@/cli/cmd/run/types"
+import { testEffect } from "../../lib/effect"
+
+const model = {
+  providerID: "openai",
+  modelID: "gpt-5",
+}
+
+const providers: RunProvider[] = [
+  {
+    id: "openai",
+    name: "OpenAI",
+    source: "api",
+    env: [],
+    options: {},
+    models: {
+      "gpt-5": {
+        id: "gpt-5",
+        providerID: "openai",
+        api: {
+          id: "gpt-5",
+          url: "https://openai.test",
+          npm: "@ai-sdk/openai",
+        },
+        name: "GPT-5",
+        capabilities: {
+          temperature: true,
+          reasoning: true,
+          attachment: true,
+          toolcall: true,
+          input: {
+            text: true,
+            audio: false,
+            image: false,
+            video: false,
+            pdf: false,
+          },
+          output: {
+            text: true,
+            audio: false,
+            image: false,
+            video: false,
+            pdf: false,
+          },
+          interleaved: false,
+        },
+        cost: {
+          input: 0,
+          output: 0,
+          cache: {
+            read: 0,
+            write: 0,
+          },
+        },
+        limit: {
+          context: 128000,
+          output: 8192,
+        },
+        status: "active",
+        options: {},
+        headers: {},
+        release_date: "2026-01-01",
+      },
+    },
+  },
+]
+
+function userMessage(
+  id: string,
+  input: { providerID: string; modelID: string; variant?: string },
+): SessionMessages[number] {
+  return {
+    info: {
+      id,
+      sessionID: "session-1",
+      role: "user",
+      time: {
+        created: 1,
+      },
+      agent: "build",
+      model: input,
+    },
+    parts: [],
+  }
+}
+
+const it = testEffect(Layer.mergeAll(FSUtil.defaultLayer, NodeFileSystem.layer))
+
+function remap(root: string, file: string) {
+  if (file === Global.Path.state) {
+    return root
+  }
+
+  if (file.startsWith(Global.Path.state + path.sep)) {
+    return path.join(root, path.relative(Global.Path.state, file))
+  }
+
+  return file
+}
+
+function remappedFs(root: string) {
+  return Layer.effect(
+    FSUtil.Service,
+    Effect.gen(function* () {
+      const fs = yield* FSUtil.Service
+      return FSUtil.Service.of({
+        ...fs,
+        readJson: (file) => fs.readJson(remap(root, file)),
+        writeJson: (file, data, mode) => fs.writeJson(remap(root, file), data, mode),
+      })
+    }),
+  ).pipe(Layer.provide(FSUtil.defaultLayer))
+}
+
+describe("run variant shared", () => {
+  test("prefers cli then session then saved variants", () => {
+    expect(resolveVariant("max", "high", "low", ["low", "high"])).toBe("max")
+    expect(resolveVariant(undefined, "high", "low", ["low", "high"])).toBe("high")
+    expect(resolveVariant(undefined, "missing", "low", ["low", "high"])).toBe("low")
+  })
+
+  test("cycles through variants and back to default", () => {
+    expect(cycleVariant(undefined, ["low", "high"])).toBe("low")
+    expect(cycleVariant("low", ["low", "high"])).toBe("high")
+    expect(cycleVariant("high", ["low", "high"])).toBeUndefined()
+    expect(cycleVariant(undefined, [])).toBeUndefined()
+  })
+
+  test("formats model labels", () => {
+    expect(formatModelLabel(model, undefined)).toBe("gpt-5 · openai")
+    expect(formatModelLabel(model, "high")).toBe("gpt-5 · openai · high")
+    expect(formatModelLabel(model, undefined, providers)).toBe("GPT-5 · OpenAI")
+    expect(formatModelLabel(model, "high", providers)).toBe("GPT-5 · OpenAI · high")
+  })
+
+  test("picks the latest matching variant from raw session messages", () => {
+    const msgs: SessionMessages = [
+      userMessage("msg-1", { providerID: "openai", modelID: "gpt-5", variant: "high" }),
+      userMessage("msg-2", { providerID: "anthropic", modelID: "sonnet", variant: "max" }),
+      userMessage("msg-3", { providerID: "openai", modelID: "gpt-5", variant: "minimal" }),
+    ]
+
+    expect(pickVariant(model, msgs)).toBe("minimal")
+  })
+
+  it.live("reads and writes saved variants through a runtime-backed app fs layer", () =>
+    Effect.gen(function* () {
+      const filesys = yield* FileSystem.FileSystem
+      const fs = yield* FSUtil.Service
+      const root = yield* filesys.makeTempDirectoryScoped()
+      const file = path.join(root, "model.json")
+
+      yield* fs.writeJson(file, {
+        recent: [{ providerID: "anthropic", modelID: "sonnet" }],
+        variant: {
+          "openai/gpt-4.1": "low",
+        },
+      })
+
+      const svc = createVariantRuntime(remappedFs(root))
+
+      yield* Effect.promise(() => svc.saveVariant(model, "high"))
+      expect(yield* Effect.promise(() => svc.resolveSavedVariant(model))).toBe("high")
+      expect(yield* fs.readJson(file)).toEqual({
+        recent: [{ providerID: "anthropic", modelID: "sonnet" }],
+        variant: {
+          "openai/gpt-4.1": "low",
+          "openai/gpt-5": "high",
+        },
+      })
+
+      yield* Effect.promise(() => svc.saveVariant(model, undefined))
+      expect(yield* Effect.promise(() => svc.resolveSavedVariant(model))).toBeUndefined()
+      expect(yield* fs.readJson(file)).toEqual({
+        recent: [{ providerID: "anthropic", modelID: "sonnet" }],
+        variant: {
+          "openai/gpt-4.1": "low",
+        },
+      })
+    }),
+  )
+
+  it.live("repairs malformed saved variant state on the next write", () =>
+    Effect.gen(function* () {
+      const filesys = yield* FileSystem.FileSystem
+      const fs = yield* FSUtil.Service
+      const root = yield* filesys.makeTempDirectoryScoped()
+      const file = path.join(root, "model.json")
+
+      yield* filesys.writeFileString(file, "{")
+
+      const svc = createVariantRuntime(remappedFs(root))
+
+      yield* Effect.promise(() => svc.saveVariant(model, "high"))
+      expect(yield* Effect.promise(() => svc.resolveSavedVariant(model))).toBe("high")
+      expect(yield* fs.readJson(file)).toEqual({
+        variant: {
+          "openai/gpt-5": "high",
+        },
+      })
+    }),
+  )
+})

packages/opencode/test/cli/serve/serve-process.test.ts

@@ -0,0 +1,61 @@
+// Subprocess integration tests for `opencode serve`. Spawns the real CLI in
+// headless mode and exercises it over HTTP — this is the only test tier that
+// catches bugs spanning argv → server boot → routing → instance loading.
+//
+// `serve` is long-lived: the harness returns a handle (url/port/kill/exited)
+// and kills the process when the test scope closes. The OS-assigned port is
+// parsed off the "listening on http://..." line.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { HttpClient } from "effect/unstable/http"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode serve (subprocess)", () => {
+  // Smoke test: server starts, binds a port, and /global/health responds.
+  // If this fails, all other serve tests likely will too — debug here first.
+  cliIt.live(
+    "starts, binds a port, and serves /global/health",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const server = yield* opencode.serve()
+        expect(server.port).toBeGreaterThan(0)
+        expect(server.url).toMatch(/^http:\/\//)
+
+        const client = yield* HttpClient.HttpClient
+        const res = yield* client.get(`${server.url}/global/health`)
+        expect(res.status).toBe(200)
+        // GlobalHealth schema is { success: true, ... } | { success: false, error }.
+        // We don't lock in further shape here — any 200 with parseable JSON is
+        // enough proof the routing + auth-bypass + instance loading is alive.
+        const body = yield* res.json
+        expect(body).toBeDefined()
+      }),
+    60_000,
+  )
+
+  // The scope-close finalizer must actually terminate the child. Without this
+  // test a regression in the kill path (e.g. a future refactor that forgets
+  // to wire the finalizer) would leak processes on every test run.
+  cliIt.live(
+    "kills the subprocess on scope close",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        // Inner scope so we can observe `.exited` resolving after it closes.
+        const exitedPromise = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const server = yield* opencode.serve()
+            // Capture the Promise, not the resolved value — scope closes after
+            // this gen returns, at which point the finalizer kills the child.
+            return server.exited
+          }),
+        )
+        // After scope close: finalizer fired, process must have exited.
+        const code = yield* Effect.promise(() => exitedPromise)
+        // Bun reports the exit code; SIGTERM-killed processes return non-null
+        // (typically 143 on POSIX). We just require resolution within a sane
+        // window — anything else means the kill didn't take.
+        expect(typeof code === "number" || code === null).toBe(true)
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/smokes/read-only.test.ts

@@ -0,0 +1,115 @@
+// Tier-A smoke tests for read-only commands. Each test asserts only that the
+// command exits 0 and produces *some* output in the isolated harness env.
+//
+// These are not behavioral tests — they're the cheapest possible signal that
+// the dependency-layer wiring (config load, DB init, server boot, provider
+// resolution) doesn't crash for the broad class of "no inputs, no side
+// effects" commands. A regression in any shared layer (an Effect.fail that
+// propagates out of a service constructor, a renamed env var, a broken DB
+// migration) will fail one or more of these tests.
+//
+// If a future change should make one of these commands intentionally fail in
+// an empty env, update the assertion + add a note explaining the new contract.
+//
+// Speed: each test pays ~1.5s for bun startup. 7 tests serialize within this
+// file. See script/prebuild-test-cli.ts for an opt-in pre-built binary that
+// cuts per-spawn cost when this suite gets bigger.
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { cliIt } from "../../lib/cli-process"
+
+describe("opencode read-only commands (smoke)", () => {
+  // `mcp list` reads MCP server config and pings each one. With the empty
+  // OPENCODE_CONFIG_CONTENT={} we provide, no servers should be configured
+  // and the command should report that cleanly.
+  cliIt.live(
+    "mcp list: exits 0",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["mcp", "list"])
+        opencode.expectExit(r, 0, "mcp list")
+      }),
+    60_000,
+  )
+
+  // `providers list` enumerates credentials + env-resolved providers.
+  // (Not config-injected ones — those don't appear here by design.) The
+  // Credentials header always renders; the Environment header only renders
+  // when at least one provider env var is set, which the isolation harness
+  // deliberately doesn't guarantee. Assert the always-present marker so the
+  // test passes on a clean CI runner without env-var leakage.
+  cliIt.live(
+    "providers list: exits 0 and prints the credentials section",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["providers", "list"])
+        opencode.expectExit(r, 0, "providers list")
+        expect(r.stdout).toContain("Credentials")
+      }),
+    60_000,
+  )
+
+  // `models` lists models from configured providers. Our test/test-model
+  // should appear because it's wired into the test provider config.
+  cliIt.live(
+    "models: exits 0 and lists the test model",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["models"])
+        opencode.expectExit(r, 0, "models")
+        expect(r.stdout).toContain("test/test-model")
+      }),
+    60_000,
+  )
+
+  // `agent list` walks the agent config. Empty config means no agents
+  // configured; the command should still exit 0 with a "no agents" line or
+  // similar. We don't pin the message — just exit cleanly.
+  cliIt.live(
+    "agent list: exits 0",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["agent", "list"])
+        opencode.expectExit(r, 0, "agent list")
+      }),
+    60_000,
+  )
+
+  // `session list` reads the session DB. Fresh OPENCODE_TEST_HOME means
+  // empty DB. Exit 0 with no sessions.
+  cliIt.live(
+    "session list: exits 0",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["session", "list"])
+        opencode.expectExit(r, 0, "session list")
+      }),
+    60_000,
+  )
+
+  // `stats` aggregates token usage from the session DB. Empty DB → all zeros.
+  cliIt.live(
+    "stats: exits 0",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["stats"])
+        opencode.expectExit(r, 0, "stats")
+      }),
+    60_000,
+  )
+
+  // `db path` prints the DB file location. Under harness isolation the DB
+  // resolves to SQLite's `:memory:` (no on-disk pollution between tests);
+  // in production it'd be a path under OPENCODE_TEST_HOME / XDG_DATA_HOME.
+  // Accept either form — both prove the resolver ran without crashing.
+  cliIt.live(
+    "db path: exits 0 and prints a path or :memory:",
+    ({ opencode }) =>
+      Effect.gen(function* () {
+        const r = yield* opencode.spawn(["db", "path"])
+        opencode.expectExit(r, 0, "db path")
+        expect(r.stdout.trim()).toMatch(/^(:memory:|[/\\].+\.(db|sqlite|sqlite3))$/i)
+      }),
+    60_000,
+  )
+})

packages/opencode/test/cli/tui/attach.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from "bun:test"
+
+describe("tui attach", () => {
+  test("loads the TUI integration lazily", async () => {
+    const source = await Bun.file(new URL("../../../src/cli/cmd/attach.ts", import.meta.url)).text()
+
+    expect(source).toContain('await import("../tui/layer")')
+    expect(source).toMatch(/await import\(["']@\/plugin\/tui\/runtime["']\)/)
+    expect(source).not.toContain('import("./app")')
+  })
+})

packages/opencode/test/cli/tui/editor-context-zed.test.ts

@@ -0,0 +1,379 @@
+import { Database } from "bun:sqlite"
+import { mkdir, symlink } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, expect, spyOn, test } from "bun:test"
+import { isZedTerminal, offsetToPosition, resolveZedDbPath, resolveZedSelection } from "@opencode-ai/tui/editor-zed"
+import { tmpdir } from "../../fixture/fixture"
+
+const originalZedTerm = process.env.ZED_TERM
+const originalTermProgram = process.env.TERM_PROGRAM
+
+afterEach(() => {
+  if (originalZedTerm === undefined) delete process.env.ZED_TERM
+  else process.env.ZED_TERM = originalZedTerm
+  if (originalTermProgram === undefined) delete process.env.TERM_PROGRAM
+  else process.env.TERM_PROGRAM = originalTermProgram
+})
+
+type ZedFixtureOptions = {
+  workspacePaths?: string | null
+  itemKind?: string
+  editor?: boolean
+  selectionStart?: number | null
+  selectionEnd?: number | null
+  selections?: Array<{ start: number | null; end: number | null }>
+  contents?: string
+}
+
+async function writeZedFixture(dir: string, options: ZedFixtureOptions = {}) {
+  const dbPath = path.join(dir, "zed.sqlite")
+  const filePath = path.join(dir, "file.ts")
+  const contents = options.contents ?? "one\ntwo\nthree"
+  await Bun.write(filePath, contents)
+
+  const db = new Database(dbPath)
+  db.run("create table workspaces (workspace_id integer, paths text, timestamp text)")
+  db.run("create table panes (pane_id integer, workspace_id integer, active integer)")
+  db.run("create table items (item_id integer, workspace_id integer, pane_id integer, active integer, kind text)")
+  db.run("create table editors (item_id integer, workspace_id integer, buffer_path text, contents text)")
+  db.run("create table editor_selections (editor_id integer, workspace_id integer, start integer, end integer)")
+  db.run("insert into workspaces values (1, ?, ?)", [options.workspacePaths ?? JSON.stringify([dir]), "2026-04-27"])
+  db.run("insert into panes values (1, 1, 1)")
+  db.run("insert into items values (1, 1, 1, 1, ?)", [options.itemKind ?? "Editor"])
+  if (options.editor !== false) {
+    db.run("insert into editors values (1, 1, ?, ?)", [filePath, contents])
+    ;(
+      options.selections ?? [
+        {
+          start: options.selectionStart === undefined ? 4 : options.selectionStart,
+          end: options.selectionEnd === undefined ? 7 : options.selectionEnd,
+        },
+      ]
+    ).forEach((selection) =>
+      db.run("insert into editor_selections values (1, 1, ?, ?)", [selection.start, selection.end]),
+    )
+  }
+  db.close()
+
+  return { dbPath, filePath }
+}
+
+function utf8ByteOffset(text: string, offset: number) {
+  return new TextEncoder().encode(text.slice(0, offset)).length
+}
+
+test("offsetToPosition converts Zed offsets to 1-based editor positions", () => {
+  expect(offsetToPosition("one\ntwo\nthree", 0)).toEqual({ line: 1, character: 1 })
+  expect(offsetToPosition("one\ntwo\nthree", 4)).toEqual({ line: 2, character: 1 })
+  expect(offsetToPosition("one\ntwo\nthree", 6)).toEqual({ line: 2, character: 3 })
+  expect(offsetToPosition("one\ntwo\nthree", 100)).toEqual({ line: 3, character: 6 })
+  expect(offsetToPosition("Ж\nabc", utf8ByteOffset("Ж\nabc", "Ж\nabc".indexOf("a")))).toEqual({
+    line: 2,
+    character: 1,
+  })
+  expect(offsetToPosition("😀\nabc", utf8ByteOffset("😀\nabc", "😀\nabc".indexOf("a")))).toEqual({
+    line: 2,
+    character: 1,
+  })
+})
+
+test("resolveZedDbPath skips candidates that cannot be stated", async () => {
+  await using tmp = await tmpdir()
+  const loop = path.join(tmp.path, "loop")
+  await symlink(loop, loop)
+  const home = spyOn(os, "homedir").mockImplementation(() => tmp.path)
+  const previous = process.env.OPENCODE_ZED_DB
+  process.env.OPENCODE_ZED_DB = loop
+
+  try {
+    expect(resolveZedDbPath()).toBeUndefined()
+  } finally {
+    if (previous === undefined) delete process.env.OPENCODE_ZED_DB
+    else process.env.OPENCODE_ZED_DB = previous
+    home.mockRestore()
+  }
+})
+
+test("isZedTerminal only returns true for Zed terminal environments", () => {
+  delete process.env.ZED_TERM
+  delete process.env.TERM_PROGRAM
+  expect(isZedTerminal()).toBeFalse()
+
+  process.env.ZED_TERM = "true"
+  expect(isZedTerminal()).toBeTrue()
+
+  process.env.ZED_TERM = "false"
+  process.env.TERM_PROGRAM = "zed"
+  expect(isZedTerminal()).toBeTrue()
+})
+
+test("resolveZedSelection returns active editor selection", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path)
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "two",
+          selection: {
+            start: { line: 2, character: 1 },
+            end: { line: 2, character: 4 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection returns all active editor selections sorted by offset", async () => {
+  await using tmp = await tmpdir()
+  const contents = "one\ntwo\nthree\nfour"
+  const fixture = await writeZedFixture(tmp.path, {
+    contents,
+    selections: [
+      {
+        start: utf8ByteOffset(contents, contents.indexOf("four")),
+        end: utf8ByteOffset(contents, contents.indexOf("four") + 4),
+      },
+      {
+        start: utf8ByteOffset(contents, contents.indexOf("two")),
+        end: utf8ByteOffset(contents, contents.indexOf("two") + 3),
+      },
+    ],
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "two",
+          selection: {
+            start: { line: 2, character: 1 },
+            end: { line: 2, character: 4 },
+          },
+        },
+        {
+          text: "four",
+          selection: {
+            start: { line: 4, character: 1 },
+            end: { line: 4, character: 5 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection converts Zed UTF-8 byte offsets to string offsets", async () => {
+  await using tmp = await tmpdir()
+  const contents = "a\nЖЖЖЖЖЖЖЖЖЖ\nb\nTARGET\nz"
+  const start = contents.indexOf("TARGET")
+  const fixture = await writeZedFixture(tmp.path, {
+    contents,
+    selectionStart: utf8ByteOffset(contents, start),
+    selectionEnd: utf8ByteOffset(contents, start + "TARGET".length),
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "TARGET",
+          selection: {
+            start: { line: 4, character: 1 },
+            end: { line: 4, character: 7 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection handles non-ASCII text inside the selected range", async () => {
+  await using tmp = await tmpdir()
+  const contents = "a\npre\nвыбор\nz"
+  const start = contents.indexOf("выбор")
+  const fixture = await writeZedFixture(tmp.path, {
+    contents,
+    selectionStart: utf8ByteOffset(contents, start),
+    selectionEnd: utf8ByteOffset(contents, start + "выбор".length),
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "выбор",
+          selection: {
+            start: { line: 3, character: 1 },
+            end: { line: 3, character: 6 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection handles emoji before the selected range", async () => {
+  await using tmp = await tmpdir()
+  const contents = "😀\nTARGET\nz"
+  const start = contents.indexOf("TARGET")
+  const fixture = await writeZedFixture(tmp.path, {
+    contents,
+    selectionStart: utf8ByteOffset(contents, start),
+    selectionEnd: utf8ByteOffset(contents, start + "TARGET".length),
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "TARGET",
+          selection: {
+            start: { line: 2, character: 1 },
+            end: { line: 2, character: 7 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection handles reversed Zed byte offsets", async () => {
+  await using tmp = await tmpdir()
+  const contents = "a\nЖЖЖ\nTARGET\nz"
+  const start = contents.indexOf("TARGET")
+  const fixture = await writeZedFixture(tmp.path, {
+    contents,
+    selectionStart: utf8ByteOffset(contents, start + "TARGET".length),
+    selectionEnd: utf8ByteOffset(contents, start),
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "TARGET",
+          selection: {
+            start: { line: 3, character: 1 },
+            end: { line: 3, character: 7 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection returns empty when no workspace matches", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path, {
+    workspacePaths: JSON.stringify([path.join(path.dirname(tmp.path), "other-workspace")]),
+  })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({ type: "empty" })
+})
+
+test("resolveZedSelection matches a Zed workspace that contains the session directory", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path)
+
+  expect(await resolveZedSelection(fixture.dbPath, path.join(tmp.path, "packages", "app"))).toEqual({
+    type: "selection",
+    selection: {
+      filePath: fixture.filePath,
+      source: "zed",
+      ranges: [
+        {
+          text: "two",
+          selection: {
+            start: { line: 2, character: 1 },
+            end: { line: 2, character: 4 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection prefers the most specific containing Zed workspace", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path)
+  const child = path.join(tmp.path, "packages")
+  const childFile = path.join(child, "child.ts")
+  await mkdir(child, { recursive: true })
+  await Bun.write(childFile, "child")
+
+  const db = new Database(fixture.dbPath)
+  db.run("insert into workspaces values (2, ?, ?)", [JSON.stringify([child]), "2026-01-01"])
+  db.run("insert into panes values (2, 2, 1)")
+  db.run("insert into items values (2, 2, 2, 1, ?)", ["Editor"])
+  db.run("insert into editors values (2, 2, ?, ?)", [childFile, "child"])
+  db.run("insert into editor_selections values (2, 2, 0, 5)")
+  db.close()
+
+  expect(await resolveZedSelection(fixture.dbPath, path.join(child, "app"))).toEqual({
+    type: "selection",
+    selection: {
+      filePath: childFile,
+      source: "zed",
+      ranges: [
+        {
+          text: "child",
+          selection: {
+            start: { line: 1, character: 1 },
+            end: { line: 1, character: 6 },
+          },
+        },
+      ],
+    },
+  })
+})
+
+test("resolveZedSelection ignores a Zed workspace nested inside the session directory", async () => {
+  await using tmp = await tmpdir()
+  const child = path.join(tmp.path, "effect-lab")
+  await mkdir(child, { recursive: true })
+  const fixture = await writeZedFixture(child)
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({ type: "empty" })
+})
+
+test("resolveZedSelection returns unavailable when a Zed terminal is active", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path, { itemKind: "Terminal", editor: false })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({ type: "unavailable" })
+})
+
+test("resolveZedSelection returns unavailable when the database cannot be queried", async () => {
+  await using tmp = await tmpdir()
+
+  expect(await resolveZedSelection(path.join(tmp.path, "missing.sqlite"), tmp.path)).toEqual({ type: "unavailable" })
+})
+
+test("resolveZedSelection returns unavailable when active selection is missing offsets", async () => {
+  await using tmp = await tmpdir()
+  const fixture = await writeZedFixture(tmp.path, { selectionStart: null, selectionEnd: null })
+
+  expect(await resolveZedSelection(fixture.dbPath, tmp.path)).toEqual({ type: "unavailable" })
+})

packages/opencode/test/cli/tui/editor-context.test.tsx

@@ -0,0 +1,297 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, expect, spyOn, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { EditorContextProvider, useEditorContext, type EditorIntegration } from "@opencode-ai/tui/context/editor"
+import { tmpdir } from "../../fixture/fixture"
+import { FakeWebSocket } from "../../lib/websocket"
+import { TestTuiContexts } from "../../fixture/tui-environment"
+import { discoverEditorConnection } from "@opencode-ai/tui/editor"
+
+const originalClaudePort = process.env.CLAUDE_CODE_SSE_PORT
+const originalOpencodePort = process.env.OPENCODE_EDITOR_SSE_PORT
+
+afterEach(() => {
+  process.env.CLAUDE_CODE_SSE_PORT = originalClaudePort
+  process.env.OPENCODE_EDITOR_SSE_PORT = originalOpencodePort
+})
+
+function nextTick() {
+  return new Promise<void>((resolve) => queueMicrotask(resolve))
+}
+
+function mountEditorContext(WebSocketImpl?: typeof WebSocket) {
+  let editor!: ReturnType<typeof useEditorContext>
+  let dispose!: () => void
+
+  createRoot((nextDispose) => {
+    dispose = nextDispose
+
+    const Consumer = () => {
+      editor = useEditorContext()
+      return null
+    }
+
+    const value = process.env.CLAUDE_CODE_SSE_PORT || process.env.OPENCODE_EDITOR_SSE_PORT
+    return (
+      <TestTuiContexts cwd={process.cwd()} paths={{ home: os.homedir() }}>
+        <EditorContextProvider integration={editorService} WebSocketImpl={WebSocketImpl}>
+          <Consumer />
+        </EditorContextProvider>
+      </TestTuiContexts>
+    )
+  })
+
+  return {
+    editor,
+    dispose,
+  }
+}
+
+const editorService: EditorIntegration = {
+  connection: discoverEditorConnection,
+}
+
+function createWebSocketImpl(...sockets: FakeWebSocket[]) {
+  let index = 0
+
+  return class {
+    constructor(url: string, options?: { headers?: Record<string, string> }) {
+      const socket = sockets[index]
+      index += 1
+      expect(socket).toBeDefined()
+      expect(url).toBe(socket!.url)
+      expect(options).toEqual(socket!.options)
+      return socket as unknown as object
+    }
+  } as unknown as typeof WebSocket
+}
+
+function sendSelection(socket: FakeWebSocket, filePath: string, text = "foo") {
+  socket.message(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      method: "selection_changed",
+      params: {
+        text,
+        filePath,
+        selection: {
+          start: { line: 1, character: 1 },
+          end: { line: 1, character: 4 },
+        },
+      },
+    }),
+  )
+}
+
+function expectedSelection(filePath: string, text = "foo") {
+  return {
+    filePath,
+    source: "websocket" as const,
+    ranges: [
+      {
+        text,
+        selection: {
+          start: { line: 1, character: 1 },
+          end: { line: 1, character: 4 },
+        },
+      },
+    ],
+  }
+}
+
+test("useEditorContext reconnect switches editor server by session directory", async () => {
+  await using tmp = await tmpdir()
+  const startupDirectory = path.join(tmp.path, "startup")
+  const sessionDirectory = path.join(tmp.path, "session")
+  const ideDirectory = path.join(tmp.path, ".claude", "ide")
+  await mkdir(startupDirectory, { recursive: true })
+  await mkdir(sessionDirectory, { recursive: true })
+  await mkdir(ideDirectory, { recursive: true })
+  await writeFile(
+    path.join(ideDirectory, "3001.lock"),
+    JSON.stringify({
+      transport: "ws",
+      workspaceFolders: [startupDirectory],
+    }),
+  )
+  await writeFile(
+    path.join(ideDirectory, "3002.lock"),
+    JSON.stringify({
+      transport: "ws",
+      workspaceFolders: [sessionDirectory],
+    }),
+  )
+
+  process.env.CLAUDE_CODE_SSE_PORT = undefined
+  process.env.OPENCODE_EDITOR_SSE_PORT = undefined
+  spyOn(process, "cwd").mockImplementation(() => startupDirectory)
+  spyOn(os, "homedir").mockImplementation(() => tmp.path)
+  const firstSocket = new FakeWebSocket("ws://127.0.0.1:3001")
+  const secondSocket = new FakeWebSocket("ws://127.0.0.1:3002")
+
+  const mounted = mountEditorContext(createWebSocketImpl(firstSocket, secondSocket))
+  await nextTick()
+
+  expect(firstSocket.closed).toBeFalse()
+  sendSelection(firstSocket, path.join(startupDirectory, "file.ts"))
+
+  expect(mounted.editor.selection()).toEqual(expectedSelection(path.join(startupDirectory, "file.ts")))
+  expect(mounted.editor.labelState()).toBe("pending")
+
+  mounted.editor.reconnect(sessionDirectory)
+  await nextTick()
+
+  expect(firstSocket.closed).toBeTrue()
+  expect(secondSocket.closed).toBeFalse()
+  expect(mounted.editor.selection()).toBeUndefined()
+  expect(mounted.editor.labelState()).toBe("none")
+
+  mounted.dispose()
+})
+
+test("useEditorContext favors configured port over lock files", async () => {
+  await using tmp = await tmpdir()
+  const startupDirectory = path.join(tmp.path, "startup")
+  const ideDirectory = path.join(tmp.path, ".claude", "ide")
+  await mkdir(startupDirectory, { recursive: true })
+  await mkdir(ideDirectory, { recursive: true })
+  await writeFile(
+    path.join(ideDirectory, "3001.lock"),
+    JSON.stringify({
+      transport: "ws",
+      workspaceFolders: [startupDirectory],
+    }),
+  )
+
+  process.env.CLAUDE_CODE_SSE_PORT = "4010"
+  process.env.OPENCODE_EDITOR_SSE_PORT = undefined
+  spyOn(process, "cwd").mockImplementation(() => startupDirectory)
+  spyOn(os, "homedir").mockImplementation(() => tmp.path)
+  const socket = new FakeWebSocket("ws://127.0.0.1:4010")
+
+  const mounted = mountEditorContext(createWebSocketImpl(socket))
+  await nextTick()
+
+  expect(socket.closed).toBeFalse()
+
+  mounted.dispose()
+})
+
+test("useEditorContext clears selection when reconnecting", async () => {
+  await using tmp = await tmpdir()
+  const startupDirectory = path.join(tmp.path, "startup")
+  const ideDirectory = path.join(tmp.path, ".claude", "ide")
+  await mkdir(startupDirectory, { recursive: true })
+  await mkdir(ideDirectory, { recursive: true })
+  await writeFile(
+    path.join(ideDirectory, "3001.lock"),
+    JSON.stringify({
+      transport: "ws",
+      workspaceFolders: [startupDirectory],
+    }),
+  )
+
+  process.env.CLAUDE_CODE_SSE_PORT = undefined
+  process.env.OPENCODE_EDITOR_SSE_PORT = undefined
+  spyOn(process, "cwd").mockImplementation(() => startupDirectory)
+  spyOn(os, "homedir").mockImplementation(() => tmp.path)
+  const socket = new FakeWebSocket("ws://127.0.0.1:3001")
+
+  const mounted = mountEditorContext(createWebSocketImpl(socket))
+  await nextTick()
+
+  expect(socket.closed).toBeFalse()
+  expect(mounted.editor.selection()).toBeUndefined()
+  expect(mounted.editor.connected()).toBeFalse()
+
+  socket.open()
+  socket.message(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      result: {
+        protocolVersion: "2025-11-25",
+        serverInfo: { name: "test", version: "0.0.0" },
+      },
+    }),
+  )
+  sendSelection(socket, path.join(startupDirectory, "file.ts"))
+
+  expect(mounted.editor.connected()).toBeTrue()
+  expect(mounted.editor.server()).toEqual({
+    protocolVersion: "2025-11-25",
+    serverInfo: { name: "test", version: "0.0.0" },
+  })
+  expect(mounted.editor.selection()).toEqual(expectedSelection(path.join(startupDirectory, "file.ts")))
+  expect(mounted.editor.labelState()).toBe("pending")
+  mounted.editor.markSelectionSent()
+  expect(mounted.editor.labelState()).toBe("sent")
+
+  mounted.editor.reconnect(startupDirectory)
+
+  expect(socket.closed).toBeFalse()
+  expect(mounted.editor.connected()).toBeTrue()
+  expect(mounted.editor.selection()).toBeUndefined()
+  expect(mounted.editor.labelState()).toBe("none")
+
+  mounted.dispose()
+})
+
+test("useEditorContext preserves selection for the next reconnect when requested", async () => {
+  await using tmp = await tmpdir()
+  const startupDirectory = path.join(tmp.path, "startup")
+  const ideDirectory = path.join(tmp.path, ".claude", "ide")
+  await mkdir(startupDirectory, { recursive: true })
+  await mkdir(ideDirectory, { recursive: true })
+  await writeFile(
+    path.join(ideDirectory, "3001.lock"),
+    JSON.stringify({
+      transport: "ws",
+      workspaceFolders: [startupDirectory],
+    }),
+  )
+
+  process.env.CLAUDE_CODE_SSE_PORT = undefined
+  process.env.OPENCODE_EDITOR_SSE_PORT = undefined
+  spyOn(process, "cwd").mockImplementation(() => startupDirectory)
+  spyOn(os, "homedir").mockImplementation(() => tmp.path)
+  const socket = new FakeWebSocket("ws://127.0.0.1:3001")
+
+  const mounted = mountEditorContext(createWebSocketImpl(socket))
+  await nextTick()
+
+  sendSelection(socket, path.join(startupDirectory, "file.ts"))
+  expect(mounted.editor.selection()).toEqual(expectedSelection(path.join(startupDirectory, "file.ts")))
+
+  mounted.editor.markSelectionSent()
+  mounted.editor.preserveSelectionFromNewSession()
+  mounted.editor.reconnect(startupDirectory)
+
+  expect(socket.closed).toBeFalse()
+  expect(mounted.editor.selection()).toEqual(expectedSelection(path.join(startupDirectory, "file.ts")))
+  expect(mounted.editor.labelState()).toBe("sent")
+
+  mounted.editor.reconnect(startupDirectory)
+
+  expect(mounted.editor.selection()).toBeUndefined()
+  expect(mounted.editor.labelState()).toBe("none")
+
+  mounted.dispose()
+})
+
+test("useEditorContext connects with OPENCODE_EDITOR_SSE_PORT", async () => {
+  await using tmp = await tmpdir()
+  process.env.CLAUDE_CODE_SSE_PORT = undefined
+  process.env.OPENCODE_EDITOR_SSE_PORT = "4020"
+  spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const socket = new FakeWebSocket("ws://127.0.0.1:4020")
+
+  const mounted = mountEditorContext(createWebSocketImpl(socket))
+  await nextTick()
+
+  expect(socket.closed).toBeFalse()
+
+  mounted.dispose()
+})

packages/opencode/test/cli/tui/plugin-add.test.ts

@@ -0,0 +1,110 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+import { TuiConfig } from "../../../src/config/tui"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("adds tui plugin at runtime from spec", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "add-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "add.txt")
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.add",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { spec, marker }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({
+      api: createTuiPluginApi(),
+      config,
+    })
+
+    await expect(TuiPluginRuntime.addPlugin(tmp.extra.spec)).resolves.toBe(true)
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("called")
+    expect(TuiPluginRuntime.list().find((item) => item.id === "demo.add")).toEqual({
+      id: "demo.add",
+      source: "file",
+      spec: tmp.extra.spec,
+      target: tmp.extra.spec,
+      enabled: true,
+      active: true,
+    })
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("retries runtime add for file plugins after dependency wait", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "retry-plugin")
+      const spec = pathToFileURL(mod).href
+      const marker = path.join(dir, "retry-add.txt")
+      await fs.mkdir(mod, { recursive: true })
+      return { mod, spec, marker }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockImplementation(async () => {
+    await Bun.write(
+      path.join(tmp.extra.mod, "index.ts"),
+      `export default {
+  id: "demo.add.retry",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(tmp.extra.marker)}, "called")
+  },
+}
+`,
+    )
+  })
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({
+      api: createTuiPluginApi(),
+      config,
+    })
+
+    await expect(TuiPluginRuntime.addPlugin(tmp.extra.spec)).resolves.toBe(true)
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("called")
+    expect(wait).toHaveBeenCalledTimes(1)
+    expect(TuiPluginRuntime.list().find((item) => item.id === "demo.add.retry")?.active).toBe(true)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})

packages/opencode/test/cli/tui/plugin-install.test.ts

@@ -0,0 +1,87 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+import { TuiConfig } from "../../../src/config/tui"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("installs plugin without loading it", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "install-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "install.txt")
+
+      await Bun.write(
+        path.join(dir, "package.json"),
+        JSON.stringify(
+          {
+            name: "demo-install-plugin",
+            type: "module",
+            exports: {
+              "./tui": {
+                import: "./install-plugin.ts",
+                config: { marker },
+              },
+            },
+          },
+          null,
+          2,
+        ),
+      )
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.install",
+  tui: async (_api, options) => {
+    if (!options?.marker) return
+    await Bun.write(options.marker, "loaded")
+  },
+}
+`,
+      )
+
+      return { spec, marker }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const api = createTuiPluginApi({
+    state: {
+      path: {
+        state: path.join(tmp.path, "state.json"),
+        config: path.join(tmp.path, "tui.json"),
+        worktree: tmp.path,
+        directory: tmp.path,
+      },
+    },
+  })
+
+  try {
+    await TuiPluginRuntime.init({ api, config })
+    const out = await TuiPluginRuntime.installPlugin(tmp.extra.spec)
+    expect(out).toMatchObject({
+      ok: true,
+      tui: true,
+    })
+
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    await expect(TuiPluginRuntime.addPlugin(tmp.extra.spec)).resolves.toBe(true)
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("loaded")
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})

packages/opencode/test/cli/tui/plugin-lifecycle.test.ts

@@ -0,0 +1,224 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { mockTuiRuntime } from "../../fixture/tui-runtime"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("runs onDispose callbacks with aborted signal and is idempotent", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "marker.txt")
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.lifecycle",
+  tui: async (api, options) => {
+    api.event.on("event.test", () => {})
+    api.route.register([{ name: "lifecycle.route", render: () => null }])
+    api.lifecycle.onDispose(async () => {
+      const prev = await Bun.file(options.marker).text().catch(() => "")
+      await Bun.write(options.marker, prev + "custom\\n")
+    })
+    api.lifecycle.onDispose(async () => {
+      const prev = await Bun.file(options.marker).text().catch(() => "")
+      await Bun.write(options.marker, prev + "aborted:" + String(api.lifecycle.signal.aborted) + "\\n")
+    })
+  },
+}
+`,
+      )
+
+      return { spec, marker }
+    },
+  })
+
+  const { config, restore } = mockTuiRuntime(tmp.path, [[tmp.extra.spec, { marker: tmp.extra.marker }]])
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await TuiPluginRuntime.dispose()
+
+    const marker = await fs.readFile(tmp.extra.marker, "utf8")
+    expect(marker).toContain("custom")
+    expect(marker).toContain("aborted:true")
+
+    // second dispose is a no-op
+    await TuiPluginRuntime.dispose()
+    const after = await fs.readFile(tmp.extra.marker, "utf8")
+    expect(after).toBe(marker)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    restore()
+  }
+})
+
+test("rolls back failed plugin and continues loading next", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const bad = path.join(dir, "bad-plugin.ts")
+      const good = path.join(dir, "good-plugin.ts")
+      const badSpec = pathToFileURL(bad).href
+      const goodSpec = pathToFileURL(good).href
+      const badMarker = path.join(dir, "bad-cleanup.txt")
+      const goodMarker = path.join(dir, "good-called.txt")
+
+      await Bun.write(
+        bad,
+        `export default {
+  id: "demo.bad",
+  tui: async (api, options) => {
+    api.route.register([{ name: "bad.route", render: () => null }])
+    api.lifecycle.onDispose(async () => {
+      await Bun.write(options.bad_marker, "cleaned")
+    })
+    throw new Error("bad plugin")
+  },
+}
+`,
+      )
+
+      await Bun.write(
+        good,
+        `export default {
+  id: "demo.good",
+  tui: async (_api, options) => {
+    await Bun.write(options.good_marker, "called")
+  },
+}
+`,
+      )
+
+      return { badSpec, goodSpec, badMarker, goodMarker }
+    },
+  })
+
+  const { config, restore } = mockTuiRuntime(tmp.path, [
+    [tmp.extra.badSpec, { bad_marker: tmp.extra.badMarker }],
+    [tmp.extra.goodSpec, { good_marker: tmp.extra.goodMarker }],
+  ])
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    // bad plugin's onDispose ran during rollback
+    await expect(fs.readFile(tmp.extra.badMarker, "utf8")).resolves.toBe("cleaned")
+    // good plugin still loaded
+    await expect(fs.readFile(tmp.extra.goodMarker, "utf8")).resolves.toBe("called")
+  } finally {
+    await TuiPluginRuntime.dispose()
+    restore()
+  }
+})
+
+test("assigns sequential slot ids scoped to plugin", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "slot-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "slot-setup.txt")
+
+      await Bun.write(
+        file,
+        `import fs from "fs"
+
+const mark = (label) => {
+  fs.appendFileSync(${JSON.stringify(marker)}, label + "\\n")
+}
+
+export default {
+  id: "demo.slot",
+  tui: async (api) => {
+    const one = api.slots.register({
+      id: 1,
+      setup: () => { mark("one") },
+      slots: { home_logo() { return null } },
+    })
+    const two = api.slots.register({
+      id: 2,
+      setup: () => { mark("two") },
+      slots: { home_bottom() { return null } },
+    })
+    mark("id:" + one)
+    mark("id:" + two)
+  },
+}
+`,
+      )
+
+      return { spec, marker }
+    },
+  })
+
+  const { config, restore } = mockTuiRuntime(tmp.path, [tmp.extra.spec])
+  const err = spyOn(console, "error").mockImplementation(() => {})
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+
+    const marker = await fs.readFile(tmp.extra.marker, "utf8")
+    expect(marker).toContain("one")
+    expect(marker).toContain("two")
+    expect(marker).toContain("id:demo.slot")
+    expect(marker).toContain("id:demo.slot:1")
+
+    // no initialization failures
+    const hit = err.mock.calls.find(
+      (item) => typeof item[0] === "string" && item[0].includes("failed to initialize tui plugin"),
+    )
+    expect(hit).toBeUndefined()
+  } finally {
+    await TuiPluginRuntime.dispose()
+    err.mockRestore()
+    restore()
+  }
+})
+
+test(
+  "times out hanging plugin cleanup on dispose",
+  async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        const file = path.join(dir, "timeout-plugin.ts")
+        const spec = pathToFileURL(file).href
+
+        await Bun.write(
+          file,
+          `export default {
+  id: "demo.timeout",
+  tui: async (api) => {
+    api.lifecycle.onDispose(() => new Promise(() => {}))
+  },
+}
+`,
+        )
+
+        return { spec }
+      },
+    })
+
+    const { config, restore } = mockTuiRuntime(tmp.path, [tmp.extra.spec])
+
+    try {
+      await TuiPluginRuntime.init({ api: createTuiPluginApi(), config, disposeTimeoutMs: 25 })
+
+      const done = await new Promise<string>((resolve) => {
+        const timer = setTimeout(() => resolve("timeout"), 500)
+        void TuiPluginRuntime.dispose().then(() => {
+          clearTimeout(timer)
+          resolve("done")
+        })
+      })
+      expect(done).toBe("done")
+    } finally {
+      await TuiPluginRuntime.dispose()
+      restore()
+    }
+  },
+  { timeout: 15000 },
+)

packages/opencode/test/cli/tui/plugin-loader-entrypoint.test.ts

@@ -0,0 +1,485 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+import { TuiConfig } from "../../../src/config/tui"
+import { Npm } from "@opencode-ai/core/npm"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("loads npm tui plugin from package ./tui export", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const marker = path.join(dir, "tui-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          exports: { ".": "./index.js", "./server": "./server.js", "./tui": "./tui.js" },
+        }),
+      )
+      await Bun.write(path.join(mod, "index.js"), 'import "./main-throws.js"\nexport default {}\n')
+      await Bun.write(path.join(mod, "main-throws.js"), 'throw new Error("main loaded")\n')
+      await Bun.write(path.join(mod, "server.js"), "export default {}\n")
+      await Bun.write(
+        path.join(mod, "tui.js"),
+        `export default {
+  id: "demo.tui.export",
+  tui: async (_api, options) => {
+    if (!options?.marker) return
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [[tmp.extra.spec, { marker: tmp.extra.marker }]],
+    plugin_origins: [
+      {
+        spec: [tmp.extra.spec, { marker: tmp.extra.marker }],
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("called")
+    const hit = TuiPluginRuntime.list().find((item) => item.id === "demo.tui.export")
+    expect(hit?.enabled).toBe(true)
+    expect(hit?.active).toBe(true)
+    expect(hit?.source).toBe("npm")
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("does not use npm package exports dot for tui entry", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const marker = path.join(dir, "dot-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          exports: { ".": "./index.js" },
+        }),
+      )
+      await Bun.write(
+        path.join(mod, "index.js"),
+        `export default {
+  id: "demo.dot",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    expect(TuiPluginRuntime.list().some((item) => item.spec === tmp.extra.spec)).toBe(false)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("rejects npm tui export that resolves outside plugin directory", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const outside = path.join(dir, "outside")
+      const marker = path.join(dir, "outside-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+      await fs.mkdir(outside, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          exports: { ".": "./index.js", "./tui": "./escape/tui.js" },
+        }),
+      )
+      await Bun.write(path.join(mod, "index.js"), "export default {}\n")
+      await Bun.write(
+        path.join(outside, "tui.js"),
+        `export default {
+  id: "demo.outside",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "outside")
+  },
+}
+`,
+      )
+      await fs.symlink(outside, path.join(mod, "escape"), process.platform === "win32" ? "junction" : "dir")
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    // plugin code never ran
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    // plugin not listed
+    expect(TuiPluginRuntime.list().some((item) => item.spec === tmp.extra.spec)).toBe(false)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("rejects npm tui plugin that exports server and tui together", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const marker = path.join(dir, "mixed-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          exports: { ".": "./index.js", "./tui": "./tui.js" },
+        }),
+      )
+      await Bun.write(path.join(mod, "index.js"), "export default {}\n")
+      await Bun.write(
+        path.join(mod, "tui.js"),
+        `export default {
+  id: "demo.mixed",
+  server: async () => ({}),
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    expect(TuiPluginRuntime.list().some((item) => item.spec === tmp.extra.spec)).toBe(false)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("does not use npm package main for tui entry", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const marker = path.join(dir, "main-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          main: "./index.js",
+        }),
+      )
+      await Bun.write(
+        path.join(mod, "index.js"),
+        `export default {
+  id: "demo.main",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+  const warn = spyOn(console, "warn").mockImplementation(() => {})
+  const error = spyOn(console, "error").mockImplementation(() => {})
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    expect(TuiPluginRuntime.list().some((item) => item.spec === tmp.extra.spec)).toBe(false)
+    expect(error).not.toHaveBeenCalled()
+    expect(warn.mock.calls.some((call) => String(call[0]).includes("tui plugin has no entrypoint"))).toBe(true)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    warn.mockRestore()
+    error.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("does not use directory package main for tui entry", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "dir-plugin")
+      const spec = pathToFileURL(mod).href
+      const marker = path.join(dir, "dir-main-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "dir-plugin",
+          type: "module",
+          main: "./main.js",
+        }),
+      )
+      await Bun.write(
+        path.join(mod, "main.js"),
+        `export default {
+  id: "demo.dir.main",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+
+      return { marker, spec }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    expect(TuiPluginRuntime.list().some((item) => item.spec === tmp.extra.spec)).toBe(false)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("uses directory index fallback for tui when package.json is missing", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "dir-index")
+      const spec = pathToFileURL(mod).href
+      const marker = path.join(dir, "dir-index-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+      await Bun.write(
+        path.join(mod, "index.ts"),
+        `export default {
+  id: "demo.dir.index",
+  tui: async () => {
+    await Bun.write(${JSON.stringify(marker)}, "called")
+  },
+}
+`,
+      )
+      return { marker, spec }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [
+      {
+        spec: tmp.extra.spec,
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("called")
+    expect(TuiPluginRuntime.list().find((item) => item.id === "demo.dir.index")?.active).toBe(true)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("uses npm package name when tui plugin id is omitted", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const mod = path.join(dir, "mods", "acme-plugin")
+      const marker = path.join(dir, "name-id-called.txt")
+      await fs.mkdir(mod, { recursive: true })
+
+      await Bun.write(
+        path.join(mod, "package.json"),
+        JSON.stringify({
+          name: "acme-plugin",
+          type: "module",
+          exports: { ".": "./index.js", "./tui": "./tui.js" },
+        }),
+      )
+      await Bun.write(path.join(mod, "index.js"), "export default {}\n")
+      await Bun.write(
+        path.join(mod, "tui.js"),
+        `export default {
+  tui: async (_api, options) => {
+    if (!options?.marker) return
+    await Bun.write(options.marker, "called")
+  },
+}
+`,
+      )
+
+      return { mod, marker, spec: "acme-plugin@1.0.0" }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [[tmp.extra.spec, { marker: tmp.extra.marker }]],
+    plugin_origins: [
+      {
+        spec: [tmp.extra.spec, { marker: tmp.extra.marker }],
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const install = spyOn(Npm, "add").mockResolvedValue({ directory: tmp.extra.mod, entrypoint: undefined })
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("called")
+    expect(TuiPluginRuntime.list().find((item) => item.spec === tmp.extra.spec)?.id).toBe("acme-plugin")
+  } finally {
+    await TuiPluginRuntime.dispose()
+    install.mockRestore()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})

packages/opencode/test/cli/tui/plugin-loader-pure.test.ts

@@ -0,0 +1,72 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+import { TuiConfig } from "../../../src/config/tui"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("skips external tui plugins in pure mode", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "called.txt")
+      const meta = path.join(dir, "plugin-meta.json")
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.pure",
+  tui: async (_api, options) => {
+    if (!options?.marker) return
+    await Bun.write(options.marker, "called")
+  },
+}
+`,
+      )
+
+      return { spec, marker, meta }
+    },
+  })
+
+  const pure = process.env.OPENCODE_PURE
+  const meta = process.env.OPENCODE_PLUGIN_META_FILE
+  process.env.OPENCODE_PURE = "1"
+  process.env.OPENCODE_PLUGIN_META_FILE = tmp.extra.meta
+
+  const config = createTuiResolvedConfig({
+    plugin: [[tmp.extra.spec, { marker: tmp.extra.marker }]],
+    plugin_origins: [
+      {
+        spec: [tmp.extra.spec, { marker: tmp.extra.marker }],
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({ api: createTuiPluginApi(), config })
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    if (pure === undefined) {
+      delete process.env.OPENCODE_PURE
+    } else {
+      process.env.OPENCODE_PURE = pure
+    }
+    if (meta === undefined) {
+      delete process.env.OPENCODE_PLUGIN_META_FILE
+    } else {
+      process.env.OPENCODE_PLUGIN_META_FILE = meta
+    }
+  }
+})

packages/opencode/test/cli/tui/plugin-toggle.test.ts

@@ -0,0 +1,264 @@
+import { expect, spyOn, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+import { tmpdir } from "../../fixture/fixture"
+import { createTuiPluginApi } from "../../fixture/tui-plugin"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+import { TuiConfig } from "../../../src/config/tui"
+
+const { TuiPluginRuntime } = await import("../../../src/plugin/tui/runtime")
+
+test("toggles plugin runtime state by exported id", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "toggle-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "toggle.txt")
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.toggle",
+  tui: async (api, options) => {
+    const text = await Bun.file(options.marker).text().catch(() => "")
+    await Bun.write(options.marker, text + "start\\n")
+    api.lifecycle.onDispose(async () => {
+      const next = await Bun.file(options.marker).text().catch(() => "")
+      await Bun.write(options.marker, next + "stop\\n")
+    })
+  },
+}
+`,
+      )
+
+      return {
+        spec,
+        marker,
+      }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [[tmp.extra.spec, { marker: tmp.extra.marker }]],
+    plugin_enabled: {
+      "demo.toggle": false,
+    },
+    plugin_origins: [
+      {
+        spec: [tmp.extra.spec, { marker: tmp.extra.marker }],
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const api = createTuiPluginApi()
+
+  try {
+    await TuiPluginRuntime.init({ api, config })
+
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).rejects.toThrow()
+    expect(TuiPluginRuntime.list().find((item) => item.id === "demo.toggle")).toEqual({
+      id: "demo.toggle",
+      source: "file",
+      spec: tmp.extra.spec,
+      target: tmp.extra.spec,
+      enabled: false,
+      active: false,
+    })
+
+    await expect(TuiPluginRuntime.activatePlugin("demo.toggle")).resolves.toBe(true)
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("start\n")
+    expect(api.kv.get("plugin_enabled", {})).toEqual({
+      "demo.toggle": true,
+    })
+
+    await expect(TuiPluginRuntime.deactivatePlugin("demo.toggle")).resolves.toBe(true)
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("start\nstop\n")
+    expect(api.kv.get("plugin_enabled", {})).toEqual({
+      "demo.toggle": false,
+    })
+
+    await expect(TuiPluginRuntime.activatePlugin("missing.id")).resolves.toBe(false)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("deactivating plugin pops pushed mode", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "mode-plugin.ts")
+      const spec = pathToFileURL(file).href
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.mode",
+  tui: async (api) => {
+    api.mode.push("demo.mode")
+  },
+}
+`,
+      )
+
+      return { spec }
+    },
+  })
+
+  const stack: { id: symbol; mode: string }[] = []
+  let popCount = 0
+  const api = createTuiPluginApi({
+    mode: {
+      current: () => stack.at(-1)?.mode ?? "base",
+      push(mode) {
+        const id = Symbol(mode)
+        let active = true
+        stack.push({ id, mode })
+        return () => {
+          if (!active) return
+          active = false
+          popCount += 1
+          const index = stack.findIndex((item) => item.id === id)
+          if (index !== -1) stack.splice(index, 1)
+        }
+      },
+    },
+  })
+  const config = createTuiResolvedConfig({
+    plugin: [tmp.extra.spec],
+    plugin_origins: [{ spec: tmp.extra.spec, scope: "local", source: path.join(tmp.path, "tui.json") }],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({ api, config })
+
+    expect(api.mode.current()).toBe("demo.mode")
+    expect(popCount).toBe(0)
+
+    await expect(TuiPluginRuntime.deactivatePlugin("demo.mode")).resolves.toBe(true)
+
+    expect(api.mode.current()).toBe("base")
+    expect(popCount).toBe(1)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+  }
+})
+
+test("kv plugin_enabled overrides tui config on startup", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "startup-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const marker = path.join(dir, "startup.txt")
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.startup",
+  tui: async (_api, options) => {
+    await Bun.write(options.marker, "on")
+  },
+}
+`,
+      )
+
+      return {
+        spec,
+        marker,
+      }
+    },
+  })
+
+  process.env.OPENCODE_PLUGIN_META_FILE = path.join(tmp.path, "plugin-meta.json")
+  const config = createTuiResolvedConfig({
+    plugin: [[tmp.extra.spec, { marker: tmp.extra.marker }]],
+    plugin_enabled: {
+      "demo.startup": false,
+    },
+    plugin_origins: [
+      {
+        spec: [tmp.extra.spec, { marker: tmp.extra.marker }],
+        scope: "local",
+        source: path.join(tmp.path, "tui.json"),
+      },
+    ],
+  })
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const api = createTuiPluginApi()
+  api.kv.set("plugin_enabled", {
+    "demo.startup": true,
+  })
+
+  try {
+    await TuiPluginRuntime.init({ api, config })
+
+    await expect(fs.readFile(tmp.extra.marker, "utf8")).resolves.toBe("on")
+    expect(TuiPluginRuntime.list().find((item) => item.id === "demo.startup")).toEqual({
+      id: "demo.startup",
+      source: "file",
+      spec: tmp.extra.spec,
+      target: tmp.extra.spec,
+      enabled: true,
+      active: true,
+    })
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+    delete process.env.OPENCODE_PLUGIN_META_FILE
+  }
+})
+
+test("loads disabled-by-default internal plugin inactive and activates on demand", async () => {
+  await using tmp = await tmpdir()
+  const config = createTuiResolvedConfig()
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+  const api = createTuiPluginApi()
+
+  try {
+    await TuiPluginRuntime.init({ api, config })
+
+    expect(TuiPluginRuntime.list().find((item) => item.id === "internal:plugin-manager")).toMatchObject({
+      enabled: true,
+      active: true,
+    })
+    expect(TuiPluginRuntime.list().find((item) => item.id === "which-key")).toEqual({
+      id: "which-key",
+      source: "internal",
+      spec: "which-key",
+      target: "which-key",
+      enabled: false,
+      active: false,
+    })
+
+    await expect(TuiPluginRuntime.activatePlugin("which-key")).resolves.toBe(true)
+    expect(TuiPluginRuntime.list().find((item) => item.id === "which-key")).toEqual({
+      id: "which-key",
+      source: "internal",
+      spec: "which-key",
+      target: "which-key",
+      enabled: true,
+      active: true,
+    })
+    expect(api.kv.get("plugin_enabled", {})).toEqual({
+      "which-key": true,
+    })
+  } finally {
+    await TuiPluginRuntime.dispose()
+    cwd.mockRestore()
+    wait.mockRestore()
+  }
+})

packages/opencode/test/cli/tui/thread.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { tmpdir } from "../../fixture/fixture"
+import { resolveThreadDirectory } from "../../../src/cli/cmd/tui"
+
+describe("tui thread", () => {
+  test("loads the TUI integration lazily", async () => {
+    const source = await Bun.file(new URL("../../../src/cli/cmd/tui.ts", import.meta.url)).text()
+
+    expect(source).toContain('await import("../tui/layer")')
+    expect(source).toMatch(/await import\(["']@\/plugin\/tui\/runtime["']\)/)
+    expect(source).not.toContain('import("./app")')
+  })
+
+  async function check(project?: string) {
+    await using tmp = await tmpdir({ git: true })
+    const link = path.join(path.dirname(tmp.path), path.basename(tmp.path) + "-link")
+    const type = process.platform === "win32" ? "junction" : "dir"
+
+    try {
+      await fs.symlink(tmp.path, link, type)
+      expect(resolveThreadDirectory(project, link, tmp.path)).toBe(tmp.path)
+    } finally {
+      await fs.rm(link, { recursive: true, force: true }).catch(() => undefined)
+    }
+  }
+
+  test("uses the real cwd when PWD points at a symlink", async () => {
+    await check()
+  })
+
+  test("uses the real cwd after resolving a relative project from PWD", async () => {
+    await check(".")
+  })
+})