@brimveyn/aimux 1.16.3 → 1.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.16.3",
+  "version": "1.18.1",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -53,7 +53,9 @@
     "demo:themes": "vhs assets/themes.tape",
     "restart-daemon": "AIMUX_PROFILE=dev bun run src/index.tsx restart-daemon",
     "restart-terminal-manager": "AIMUX_PROFILE=dev bun run src/index.tsx restart-terminal-manager",
+    "reexec-test": "AIMUX_PROFILE=reexec-test AIMUX_HOT_REEXEC=1 bun run scripts/manual-reexec-test.ts",
     "lint": "oxlint --type-aware .",
+    "lint:protocol": "bun run scripts/check-protocol-discipline.ts",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "knip": "knip-bun",
@@ -62,7 +64,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.6.12",
+    "@brimveyn/aimux-config": "0.8.1",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/app-runtime/backend-runtime-events.ts

@@ -7,11 +7,19 @@ import type {
   TabActivity,
   TabSession,
   TerminalModeState,
+  WorktreeRecord,
 } from '../state/types'
 import type { TabRuntimeTimeouts } from './tab-runtime-timeouts'
 
 import { logInputDebug } from '../debug/input-log'
 import { clearTabSyntaxState, highlightSnapshot } from '../integrations/claude-syntax-overlay'
+import { appStore } from '../state/app-store'
+import { loadSessionCatalog, saveSessionCatalog } from '../state/session-catalog'
+import {
+  handleCreateSessionEffect,
+  handleDeleteSessionEffect,
+  handleSwitchSessionEffect,
+} from './session-actions'
 
 interface BindBackendRuntimeEventsOptions {
   backend: SessionBackend
@@ -88,11 +96,175 @@ export function bindBackendRuntimeEvents({
     dispatch({ activity, tabId, type: 'set-tab-activity' })
   }
 
+  // Serialise workspace lifecycle handlers behind a small FIFO so back-to-back
+  // switch/create/close broadcasts from multiple CLIs don't race the
+  // in-flight `handleSwitchSessionEffect`. Every lifecycle handler awaits the
+  // previous chain link before running.
+  let lifecycleChain: Promise<void> = Promise.resolve()
+  const enqueueLifecycle = (fn: () => void | Promise<void>): void => {
+    const previous = lifecycleChain
+    lifecycleChain = (async () => {
+      await previous
+      try {
+        await fn()
+      } catch (error) {
+        logInputDebug('app.backend.event.lifecycle.error', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    })()
+  }
+
+  const handleWorkspaceCreateRequested = (
+    name: string,
+    projectPath: string | undefined,
+    doSwitch: boolean
+  ) => {
+    enqueueLifecycle(() => {
+      logInputDebug('app.backend.event.workspaceCreateRequested', { doSwitch, name, projectPath })
+      const state = appStore.getState()
+      handleCreateSessionEffect(state, dispatch, name, projectPath)
+      if (doSwitch) {
+        // The create dispatched `set-sessions`+`load-session`; the new session
+        // is now in the catalog + current. Loading already ran, so the switch
+        // is effectively done — just tell the daemon so any --wait CLI exits.
+        const created = appStore
+          .getState()
+          .sessions.find((s) => s.name === name && s.projectPath === projectPath)
+        if (created) backend.announceWorkspaceSwitched(created.id)
+      }
+    })
+  }
+
+  const handleWorkspaceSwitchRequested = (targetSessionId: string) => {
+    enqueueLifecycle(async () => {
+      logInputDebug('app.backend.event.workspaceSwitchRequested', { targetSessionId })
+      let state = appStore.getState()
+      let target = state.sessions.find((s) => s.id === targetSessionId)
+      if (!target) {
+        // In-memory list is stale (e.g. daemon just added a session via the
+        // headless path). Reload from disk and try once more before giving
+        // up — the daemon already validated the catalog, so this should hit.
+        const fresh = loadSessionCatalog()
+        target = fresh.find((s) => s.id === targetSessionId)
+        if (target) {
+          dispatch({ sessions: fresh, type: 'set-sessions' })
+          state = appStore.getState()
+        }
+      }
+      if (!target) {
+        // Announce anyway so any `--wait` CLI unblocks — better a spurious
+        // exit than a 30s hang while the caller retries.
+        logInputDebug('app.backend.event.workspaceSwitchRequested.notFound', { targetSessionId })
+        backend.announceWorkspaceSwitched(targetSessionId)
+        return
+      }
+      handleSwitchSessionEffect(state, backend, dispatch, target)
+      // Give the reducer a tick to settle before announcing — the switch
+      // fires `set-sessions`+`load-session` synchronously but the backend
+      // re-attach happens async.
+      await Promise.resolve()
+      backend.announceWorkspaceSwitched(targetSessionId)
+    })
+  }
+
+  const handleWorkspaceCloseRequested = (targetSessionId: string) => {
+    enqueueLifecycle(() => {
+      logInputDebug('app.backend.event.workspaceCloseRequested', { targetSessionId })
+      const state = appStore.getState()
+      handleDeleteSessionEffect(state, backend, dispatch, targetSessionId)
+    })
+  }
+
+  const handleWorkspaceSwitched = (sessionId: string) => {
+    // The daemon's own relay for --wait CLIs. UI side has no work to do —
+    // logging is enough.
+    logInputDebug('app.backend.event.workspaceSwitched', { sessionId })
+  }
+
+  const handleWorktreeAdded = (sessionId: string, worktree: WorktreeRecord) => {
+    // Idempotent: skip if a duplicate id is already in the session (the CLI
+    // may have raced the UI's own worktree-add path).
+    const current = appStore.getState()
+    const session = current.sessions.find((s) => s.id === sessionId)
+    const already = session?.worktrees?.some((w) => w.id === worktree.id) === true
+    if (already) {
+      logInputDebug('app.backend.event.worktreeAdded.skipDuplicate', {
+        sessionId,
+        worktreeId: worktree.id,
+      })
+      return
+    }
+    logInputDebug('app.backend.event.worktreeAdded', {
+      sessionId,
+      worktreeId: worktree.id,
+    })
+    dispatch({ sessionId, type: 'add-worktree-record', worktree })
+    // Persist the catalog so the change survives restart even if no other
+    // side-effect saves shortly after.
+    saveSessionCatalog(appStore.getState().sessions)
+  }
+
+  const handleWorktreeRemoved = (sessionId: string, worktreeId: string) => {
+    const current = appStore.getState()
+    const session = current.sessions.find((s) => s.id === sessionId)
+    const present = session?.worktrees?.some((w) => w.id === worktreeId) === true
+    if (!present) {
+      logInputDebug('app.backend.event.worktreeRemoved.skipMissing', { sessionId, worktreeId })
+      return
+    }
+    logInputDebug('app.backend.event.worktreeRemoved', { sessionId, worktreeId })
+    // Build the updated sessions list and dispatch via `set-sessions` — this
+    // matches the pattern used by the existing worktree-delete side-effect
+    // and centralises the write in one action rather than adding a new one.
+    const sessions = current.sessions.map((s) => {
+      if (s.id !== sessionId) return s
+      const remaining = (s.worktrees ?? []).filter((w) => w.id !== worktreeId)
+      return {
+        ...s,
+        activeWorktreeId: s.activeWorktreeId === worktreeId ? remaining[0]?.id : s.activeWorktreeId,
+        updatedAt: new Date().toISOString(),
+        worktrees: remaining,
+      }
+    })
+    saveSessionCatalog(sessions)
+    dispatch({ sessions, type: 'set-sessions' })
+  }
+
+  const handleTabAdded = (sessionId: string, tab: TabSession) => {
+    // Idempotent: the daemon broadcasts `tabAdded` for every createTab,
+    // including the ones this UI process initiated (which already dispatched
+    // `add-tab` locally). Skip the duplicate so we don't get two entries for
+    // the same tab id.
+    const current = appStore.getState()
+    if (current.tabs.some((t) => t.id === tab.id)) {
+      logInputDebug('app.backend.event.tabAdded.skipDuplicate', { sessionId, tabId: tab.id })
+      return
+    }
+    if (current.currentSessionId !== sessionId) {
+      logInputDebug('app.backend.event.tabAdded.skipForeignSession', {
+        currentSessionId: current.currentSessionId,
+        sessionId,
+        tabId: tab.id,
+      })
+      return
+    }
+    logInputDebug('app.backend.event.tabAdded', { sessionId, tabId: tab.id })
+    dispatch({ tab, type: 'add-tab' })
+  }
+
   backend.on('render', handleRender)
   backend.on('exit', handleExit)
   backend.on('error', handleError)
   backend.on('sessionActivity', handleSessionActivity)
   backend.on('tabActivity', handleTabActivity)
+  backend.on('tabAdded', handleTabAdded)
+  backend.on('workspaceCreateRequested', handleWorkspaceCreateRequested)
+  backend.on('workspaceSwitchRequested', handleWorkspaceSwitchRequested)
+  backend.on('workspaceCloseRequested', handleWorkspaceCloseRequested)
+  backend.on('workspaceSwitched', handleWorkspaceSwitched)
+  backend.on('worktreeAdded', handleWorktreeAdded)
+  backend.on('worktreeRemoved', handleWorktreeRemoved)
 
   return () => {
     timeouts.clearAllTimers()
@@ -101,6 +273,13 @@ export function bindBackendRuntimeEvents({
     backend.off('error', handleError)
     backend.off('sessionActivity', handleSessionActivity)
     backend.off('tabActivity', handleTabActivity)
+    backend.off('tabAdded', handleTabAdded)
+    backend.off('workspaceCreateRequested', handleWorkspaceCreateRequested)
+    backend.off('workspaceSwitchRequested', handleWorkspaceSwitchRequested)
+    backend.off('workspaceCloseRequested', handleWorkspaceCloseRequested)
+    backend.off('workspaceSwitched', handleWorkspaceSwitched)
+    backend.off('worktreeAdded', handleWorktreeAdded)
+    backend.off('worktreeRemoved', handleWorktreeRemoved)
     void backend.destroy(true)
   }
 }

package/src/app-runtime/side-effects.ts

@@ -326,7 +326,7 @@ export function startTabSession(
   dispatch: (action: AppAction) => void,
   clearStartupGrace: (tabId: string) => void,
   startStartupGrace: (tabId: string) => void,
-  tab: Pick<TabSession, 'id' | 'assistant' | 'title' | 'command'>,
+  tab: Pick<TabSession, 'id' | 'assistant' | 'title' | 'command' | 'worktreeId'>,
   cols: number,
   rows: number,
   cwd?: string
@@ -338,6 +338,7 @@ export function startTabSession(
     rows,
     tabId: tab.id,
     title: tab.title,
+    worktreeId: tab.worktreeId ?? null,
   })
   startStartupGrace(tab.id)
 
@@ -362,6 +363,7 @@ export function startTabSession(
     rows,
     tabId: tab.id,
     title: tab.title,
+    worktreeId: tab.worktreeId,
   })
 }
 

package/src/app.tsx

@@ -502,6 +502,32 @@ export function App({
     }
   }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
+  const flashPendingJump = useAppStore((s) =>
+    s.modal.type === 'flash-jump' ? s.modal.pendingJump : null
+  )
+  useEffect(() => {
+    if (flashPendingJump === null) return
+    // Snapshot before clearing the modal: closing rewrites state.modal so we
+    // need the target in hand before dispatching.
+    const target = flashPendingJump
+    dispatch({ type: 'close-modal' })
+    if (target.kind === 'tab' && target.tabId != null && target.tabId !== '') {
+      dispatch({ tabId: target.tabId, type: 'set-active-tab' })
+      return
+    }
+    if (target.kind === 'workspace' || target.kind === 'worktree') {
+      executeSideEffect(
+        {
+          index: target.sessionIndex,
+          type: 'switch-session-by-index',
+          worktreeId: target.worktreeId,
+        },
+        sideEffectCtx
+      )
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [flashPendingJump])
+
   useKeyboard((key) => {
     const currentState = stateRef.current
     // Global quit: Ctrl+C in any mode except terminal-input

package/src/cli/chord.ts

@@ -0,0 +1,77 @@
+import { parseKeyNotation } from '../input/keymap/key-chord'
+
+/**
+ * Map a vim-style key notation string ("<C-c>", "<Esc>", "ga", "<C-x><C-s>")
+ * into the raw bytes the receiving terminal expects. Reuses
+ * `parseKeyNotation` to turn the notation into canonical chord strings, then
+ * lowers each chord into a byte sequence.
+ *
+ * Recognised special keys:
+ *   <CR>/<Tab>/<Esc>/<Space>/<BS>/<Up>/<Down>/<Left>/<Right>
+ * Recognised modifier: `<C-letter>` (Ctrl) — case insensitive `C-`.
+ */
+export function notationToBytes(notation: string): Buffer {
+  const chords = parseKeyNotation(notation)
+  const parts: Buffer[] = []
+  for (const chord of chords) {
+    parts.push(chordToBytes(chord))
+  }
+  return Buffer.concat(parts)
+}
+
+const ESC_BRACKET = Buffer.from([0x1b, 0x5b])
+
+function chordToBytes(chord: string): Buffer {
+  if (chord.length === 1) {
+    return Buffer.from(chord, 'utf8')
+  }
+
+  // Modifier+letter (Ctrl only — Alt/Meta lowering is more terminal-specific).
+  if (chord.startsWith('C-') && chord.length >= 3) {
+    const tail = chord.slice(2)
+    if (tail.length === 1) {
+      const ch = tail.toLowerCase()
+      const code = ch.charCodeAt(0)
+      if (code >= 0x61 && code <= 0x7a) {
+        return Buffer.from([code - 0x60])
+      }
+    }
+    if (tail === 'space') return Buffer.from([0x00])
+    if (tail === '?') return Buffer.from([0x7f])
+  }
+
+  switch (chord) {
+    case 'return':
+      return Buffer.from([0x0d])
+    case 'tab':
+      return Buffer.from([0x09])
+    case 'escape':
+      return Buffer.from([0x1b])
+    case 'space':
+      return Buffer.from([0x20])
+    case 'backspace':
+      return Buffer.from([0x7f])
+    case 'up':
+      return Buffer.concat([ESC_BRACKET, Buffer.from([0x41])])
+    case 'down':
+      return Buffer.concat([ESC_BRACKET, Buffer.from([0x42])])
+    case 'right':
+      return Buffer.concat([ESC_BRACKET, Buffer.from([0x43])])
+    case 'left':
+      return Buffer.concat([ESC_BRACKET, Buffer.from([0x44])])
+    default:
+      throw new Error(`unsupported chord: ${chord}`)
+  }
+}
+
+const BRACKETED_PASTE_START = '\x1b[200~'
+const BRACKETED_PASTE_END = '\x1b[201~'
+
+/**
+ * Wrap a multi-line block in bracketed-paste markers so the receiver does not
+ * treat each `\n` as a submit keystroke. Single-line text is passed through.
+ */
+export function bracketedPaste(text: string): string {
+  if (!text.includes('\n')) return text
+  return `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}`
+}

package/src/cli/client/bootstrap.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs'
+
+import { getIpcDaemonSocketPath } from '../../daemon/runtime-paths'
+import { spawnDetachedIpcDaemon } from '../../platform/daemon-control'
+import { DaemonClient } from './daemon-client'
+
+interface ConnectOptions {
+  /** When true (default), spawn the daemon if the socket is missing. */
+  autostart?: boolean
+}
+
+const SPAWN_BACKOFF_MS = 300
+const SPAWN_ATTEMPTS = 10
+
+/**
+ * Raised only from the bootstrap phase (connecting to / spawning the daemon).
+ * The top-level CLI runner catches this and maps to EXIT_DAEMON_UNREACHABLE,
+ * distinguishing genuine connection failures from downstream runtime errors
+ * whose messages might happen to mention "socket" or "daemon".
+ */
+export class DaemonUnreachableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'DaemonUnreachableError'
+  }
+}
+
+/**
+ * Connect to the daemon, spawning it if necessary. Matches the UI's bootstrap
+ * but stripped of the breaking-update path — a CLI invocation is not the
+ * right place to surface "your binary is out of date" UX.
+ *
+ * Returns a connected, handshake-completed `DaemonClient`.
+ */
+export async function connectToDaemon(options: ConnectOptions = {}): Promise<DaemonClient> {
+  const autostart = options.autostart !== false
+  const socketPath = getIpcDaemonSocketPath()
+
+  if (existsSync(socketPath)) {
+    try {
+      return await DaemonClient.connect(socketPath)
+    } catch (error) {
+      if (!autostart) {
+        throw new DaemonUnreachableError(
+          `daemon socket unreachable: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+      // Fall through to spawn — the socket exists but the daemon is wedged.
+    }
+  }
+
+  if (!autostart) {
+    throw new DaemonUnreachableError(`daemon socket missing: ${socketPath}`)
+  }
+
+  const spawned = await spawnDetachedIpcDaemon()
+  if (!spawned) {
+    throw new DaemonUnreachableError('failed to start aimux daemon')
+  }
+
+  let lastError: unknown
+  for (let attempt = 0; attempt < SPAWN_ATTEMPTS; attempt++) {
+    try {
+      return await DaemonClient.connect(socketPath)
+    } catch (error) {
+      lastError = error
+      await new Promise((resolve) => setTimeout(resolve, SPAWN_BACKOFF_MS))
+    }
+  }
+
+  throw new DaemonUnreachableError(
+    `daemon spawned but unreachable after ${SPAWN_ATTEMPTS} attempts: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`
+  )
+}

package/src/cli/client/daemon-client.ts

@@ -0,0 +1,228 @@
+import { connect, type Socket } from 'node:net'
+
+import {
+  type AttachRequest,
+  type AttachResult,
+  type ClientRequest,
+  encodeMessage,
+  IPC_PROTOCOL_MIN_VERSION,
+  IPC_PROTOCOL_VERSION,
+  type ListTabsResult,
+  MessageDecoder,
+  parseServerMessage,
+  type ProtocolHelloResult,
+  type ServerEvent,
+  type ServerResponse,
+} from '../../ipc/protocol'
+
+interface PendingRequest {
+  resolve: (response: ServerResponse) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+type ServerEventType = ServerEvent['type']
+
+type EventHandler<T extends ServerEventType> = (
+  payload: Extract<ServerEvent, { type: T }>['payload']
+) => void
+
+const REQUEST_TIMEOUT_MS = 10_000
+
+/**
+ * Thin daemon-side client used by the CLI. Mirrors the UI's `IpcClient` but
+ * trimmed down: no React store wiring, no presence tracking, no auto-reconnect
+ * loop — the CLI is one-shot. The connection lives only as long as the
+ * command runs.
+ *
+ * Capability checks are exposed so command implementations can gate on
+ * `listTabs` / `thinAttach` / `createTabSizeFallback` and fall back cleanly
+ * when the daemon predates v11.
+ */
+export class DaemonClient {
+  private constructor(
+    private readonly socket: Socket,
+    private readonly hello: ProtocolHelloResult,
+    private readonly pending: Map<string, PendingRequest>,
+    private readonly eventHandlers: Map<
+      ServerEventType,
+      Set<(payload: ServerEvent['payload']) => void>
+    >
+  ) {}
+
+  static async connect(socketPath: string): Promise<DaemonClient> {
+    const socket = connect(socketPath)
+    await new Promise<void>((resolve, reject) => {
+      const onConnect = () => {
+        socket.off('error', onError)
+        resolve()
+      }
+      const onError = (error: Error) => {
+        socket.off('connect', onConnect)
+        reject(error)
+      }
+      socket.once('connect', onConnect)
+      socket.once('error', onError)
+    })
+
+    const pending = new Map<string, PendingRequest>()
+    const eventHandlers = new Map<ServerEventType, Set<(payload: ServerEvent['payload']) => void>>()
+    const decoder = new MessageDecoder<ServerResponse | ServerEvent>(parseServerMessage)
+
+    const failAllPending = (reason: string): void => {
+      for (const [id, entry] of pending) {
+        clearTimeout(entry.timer)
+        pending.delete(id)
+        entry.reject(new Error(reason))
+      }
+    }
+
+    socket.on('data', (chunk) => {
+      try {
+        for (const message of decoder.push(chunk)) {
+          if ('id' in message) {
+            const entry = pending.get(message.id)
+            if (entry) {
+              clearTimeout(entry.timer)
+              pending.delete(message.id)
+              entry.resolve(message)
+            }
+            continue
+          }
+          const handlers = eventHandlers.get(message.type)
+          if (!handlers) continue
+          for (const handler of handlers) handler(message.payload)
+        }
+      } catch (error) {
+        failAllPending(
+          `daemon parse error: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+    })
+    socket.on('close', () => failAllPending('daemon connection closed'))
+    socket.on('error', (error) => failAllPending(`daemon socket error: ${error.message}`))
+
+    // Handshake.
+    const id = crypto.randomUUID()
+    const helloResponse = await new Promise<ServerResponse>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id)
+        reject(new Error('hello timed out'))
+      }, REQUEST_TIMEOUT_MS)
+      pending.set(id, { reject, resolve, timer })
+      socket.write(
+        encodeMessage({
+          id,
+          payload: { maxVersion: IPC_PROTOCOL_VERSION, minVersion: IPC_PROTOCOL_MIN_VERSION },
+          type: 'hello',
+        })
+      )
+    })
+    if (helloResponse.type !== 'helloResult') {
+      const detail =
+        helloResponse.type === 'error' ? helloResponse.payload.message : helloResponse.type
+      throw new Error(`hello failed: ${detail}`)
+    }
+
+    return new DaemonClient(socket, helloResponse.payload, pending, eventHandlers)
+  }
+
+  hasCapability(name: string): boolean {
+    return this.hello.capabilities.includes(name)
+  }
+
+  getCapabilities(): readonly string[] {
+    return this.hello.capabilities
+  }
+
+  getSelectedVersion(): number {
+    return this.hello.selectedVersion
+  }
+
+  private async send(request: ClientRequest): Promise<ServerResponse> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(request.id)
+        reject(new Error(`request timed out: ${request.type}`))
+      }, REQUEST_TIMEOUT_MS)
+      this.pending.set(request.id, { reject, resolve, timer })
+      this.socket.write(encodeMessage(request), (error) => {
+        if (error) {
+          clearTimeout(timer)
+          this.pending.delete(request.id)
+          reject(error)
+        }
+      })
+    })
+  }
+
+  async request<T extends ClientRequest['type']>(
+    type: T,
+    payload: Extract<ClientRequest, { type: T }>['payload']
+  ): Promise<ServerResponse> {
+    return this.send({ id: crypto.randomUUID(), payload, type } as ClientRequest)
+  }
+
+  async expectOk(type: ClientRequest['type'], payload: unknown): Promise<void> {
+    const response = await this.send({
+      id: crypto.randomUUID(),
+      payload,
+      type,
+    } as ClientRequest)
+    if (response.type === 'ok') return
+    throw new Error(
+      response.type === 'error' ? response.payload.message : `unexpected response: ${response.type}`
+    )
+  }
+
+  async attach(request: Omit<AttachRequest, 'protocolVersion'>): Promise<AttachResult> {
+    const response = await this.send({
+      id: crypto.randomUUID(),
+      payload: { ...request, protocolVersion: this.hello.selectedVersion },
+      type: 'attach',
+    })
+    if (response.type !== 'attachResult') {
+      throw new Error(
+        response.type === 'error' ? response.payload.message : `attach failed: ${response.type}`
+      )
+    }
+    return response.payload
+  }
+
+  async listTabs(sessionId: string): Promise<ListTabsResult> {
+    const response = await this.send({
+      id: crypto.randomUUID(),
+      payload: { sessionId },
+      type: 'listTabs',
+    })
+    if (response.type !== 'listTabsResult') {
+      throw new Error(
+        response.type === 'error' ? response.payload.message : `listTabs failed: ${response.type}`
+      )
+    }
+    return response.payload
+  }
+
+  on<T extends ServerEventType>(eventType: T, handler: EventHandler<T>): () => void {
+    let set = this.eventHandlers.get(eventType)
+    if (!set) {
+      set = new Set()
+      this.eventHandlers.set(eventType, set)
+    }
+    const cast = handler as (payload: ServerEvent['payload']) => void
+    set.add(cast)
+    return () => {
+      set?.delete(cast)
+    }
+  }
+
+  close(): void {
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer)
+      this.pending.delete(id)
+      entry.reject(new Error('client closed'))
+    }
+    this.socket.end()
+    this.socket.destroy()
+  }
+}