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/
2026-06-13 21:41:54 +08:00
commit af3016fe27
5757 changed files with 1170017 additions and 0 deletions
--- a/packages/opencode/test/cli/tui/attach.test.ts
+++ b/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")')
+  })
+})
--- a/packages/opencode/test/cli/tui/editor-context-zed.test.ts
+++ b/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" })
+})
--- a/packages/opencode/test/cli/tui/editor-context.test.tsx
+++ b/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()
+})
--- a/packages/opencode/test/cli/tui/plugin-add.test.ts
+++ b/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
+  }
+})
--- a/packages/opencode/test/cli/tui/plugin-install.test.ts
+++ b/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
+  }
+})
--- a/packages/opencode/test/cli/tui/plugin-lifecycle.test.ts
+++ b/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 },
+)
--- a/packages/opencode/test/cli/tui/plugin-loader-entrypoint.test.ts
+++ b/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
+  }
+})
--- a/packages/opencode/test/cli/tui/plugin-loader-pure.test.ts
+++ b/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
+    }
+  }
+})
--- a/packages/opencode/test/cli/tui/plugin-loader.test.ts
+++ b/packages/opencode/test/cli/tui/plugin-loader.test.ts
--- a/packages/opencode/test/cli/tui/plugin-toggle.test.ts
+++ b/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()
+  }
+})
--- a/packages/opencode/test/cli/tui/thread.test.ts
+++ b/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(".")
+  })
+})