@brimveyn/aimux 1.18.4 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.18.4",
+  "version": "1.19.0",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/src/cli/commands/tab/list.ts

@@ -1,20 +1,51 @@
 import type { CliCommand } from '../../registry'
 
-import { IPC_CAPABILITY_LIST_TABS, IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import {
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_LIST_TABS_LAST_LINE,
+  IPC_CAPABILITY_THIN_ATTACH,
+  type TabSessionSummary,
+} from '../../../ipc/protocol'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 
+/**
+ * The daemon always populates `lastLine` on `listTabs` summaries (it's cheap),
+ * but the field bloats the common poll, so we strip it unless `--verbose` was
+ * asked for. Keeping the default output byte-identical to pre-v13 avoids
+ * churning downstream consumers.
+ */
+function stripLastLine(tab: TabSessionSummary): TabSessionSummary {
+  const { lastLine: _lastLine, ...rest } = tab
+  return rest
+}
+
 export const tabList: CliCommand = {
   args: [],
-  flags: SHARED_FLAGS,
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: "include each tab's last non-blank rendered line",
+      kind: 'boolean',
+      name: 'verbose',
+    },
+  ],
   group: 'tab',
   run: async (ctx) => {
     const workspace = ctx.getWorkspace()
     const daemon = await ctx.getDaemon()
+    const verbose = ctx.args.flags.verbose === true
+
+    if (verbose && !daemon.hasCapability(IPC_CAPABILITY_LIST_TABS_LAST_LINE)) {
+      throw new Error(
+        'daemon predates tab list --verbose (listTabsLastLine) — restart aimux to pick up the new daemon'
+      )
+    }
 
     if (daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
       const result = await daemon.listTabs(workspace.id)
-      writeJson({ activeTabId: result.activeTabId, tabs: result.tabs })
+      const tabs = verbose ? result.tabs : result.tabs.map(stripLastLine)
+      writeJson({ activeTabId: result.activeTabId, tabs })
       return EXIT_OK
     }
 

package/src/cli/commands/tab/prompt-io.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared prompt-write plumbing for `tab send` and `tab run`. Both need to lower
+ * a chord/paste buffer into the protocol's string form and submit it with the
+ * bracketed-paste `\r` deferral, so the logic lives here once.
+ */
+import type { DaemonClient } from '../../client/daemon-client'
+
+import { bracketedPaste, notationToBytes } from '../../chord'
+
+/**
+ * Gap between the bracketed-paste write and the trailing carriage return when
+ * submitting a pasted block. Claude Code (and other paste-aware TUIs) buffer
+ * every byte between the paste-start/paste-end markers; a `\r` that arrives in
+ * the same burst as the paste-end marker is folded into the paste buffer as
+ * literal content instead of being read as a submit keystroke. A short settle
+ * lets the receiver exit paste mode before the Enter lands.
+ */
+export const PASTE_SUBMIT_SETTLE_MS = 50
+
+/**
+ * Lower a chord/paste buffer of bytes into the string the protocol expects.
+ * Every byte we emit is < 0x80 (control chars or printable ASCII), so a
+ * Latin-1 decode is faithful — the receiving PTY's UTF-8 path treats each
+ * single byte as itself.
+ */
+function bytesToString(bytes: Buffer): string {
+  let out = ''
+  for (const byte of bytes) {
+    out += String.fromCharCode(byte)
+  }
+  return out
+}
+
+export interface PromptPayload {
+  /** The protocol-ready string to write. */
+  data: string
+  /**
+   * Whether `data` is a bracketed-paste block. A trailing `\r` must be sent as
+   * a separate, settled write for these — see PASTE_SUBMIT_SETTLE_MS.
+   */
+  bracketed: boolean
+}
+
+/**
+ * Build the payload for a prompt. `asKeys` interprets the text as a vim-style
+ * chord (e.g. `<C-c>`); otherwise it's wrapped as a bracketed paste when
+ * multi-line.
+ */
+export function buildPromptPayload(text: string, asKeys: boolean): PromptPayload {
+  if (asKeys) {
+    return { bracketed: false, data: bytesToString(notationToBytes(text)) }
+  }
+  const data = bracketedPaste(text)
+  return { bracketed: data !== text, data }
+}
+
+/**
+ * Write a prompt payload to a tab, optionally appending a submit `\r`. The
+ * payload write and the Enter are always separate `write` requests; for a
+ * bracketed paste the Enter is deferred by PASTE_SUBMIT_SETTLE_MS so it isn't
+ * swallowed by the paste buffer. Returns the number of bytes written.
+ */
+export async function writePromptPayload(
+  daemon: DaemonClient,
+  tabId: string,
+  payload: PromptPayload,
+  appendEnter: boolean
+): Promise<number> {
+  await daemon.expectOk('write', { data: payload.data, tabId })
+  let bytesWritten = Buffer.byteLength(payload.data, 'utf8')
+  if (appendEnter) {
+    // A bracketed paste swallows a same-burst `\r`, so settle first, then
+    // submit as an independent write. Plain text / key chords carry no paste
+    // markers, so the Enter can follow immediately — but still as its own
+    // write so the two paths stay uniform.
+    if (payload.bracketed) {
+      await Bun.sleep(PASTE_SUBMIT_SETTLE_MS)
+    }
+    await daemon.expectOk('write', { data: '\r', tabId })
+    bytesWritten += 1
+  }
+  return bytesWritten
+}

package/src/cli/commands/tab/run.ts

@@ -0,0 +1,222 @@
+/**
+ * `aimux tab run <tabId>` — the one authoritative verb an orchestrator needs to
+ * drive a worker turn. It collapses the spawn→send→uptake→await→snapshot chain
+ * into a single event-driven call: stage the prompt, submit it, then block on
+ * the daemon's v13 turn-lifecycle events (`tabTurnComplete` / `tabQuestion`)
+ * until the turn ends, the worker asks something, the tab dies, or the overall
+ * timeout trips. Exactly one JSON object is emitted and the exit code encodes
+ * the outcome, so a driver can branch without re-snapshotting the screen.
+ */
+import type { QuestionKind } from '../../../state/types'
+import type { CliCommand } from '../../registry'
+
+import {
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+} from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_QUESTION, EXIT_RUNTIME, EXIT_TIMEOUT, writeJson } from '../../output'
+import { buildPromptPayload, writePromptPayload } from './prompt-io'
+
+/** Overall cap on a single turn — 15 min, long enough for a heavy build task. */
+const DEFAULT_TIMEOUT_MS = 900_000
+
+/**
+ * The four terminal shapes of a `tab run`. Modelled as a discriminated union so
+ * the JSON we emit and the exit code we return are derived from one value, and
+ * so the outcome→exit mapping can be unit-tested without a live daemon.
+ * `durationMs` is measured from prompt submit, not attach, so it reflects the
+ * worker's think time rather than our connection overhead.
+ */
+export type RunOutcome =
+  | { durationMs: number; outcome: 'completed' }
+  | { durationMs: number; error: string; outcome: 'error' }
+  | {
+      durationMs: number
+      kind: QuestionKind
+      options?: string[]
+      outcome: 'question'
+      question: string
+    }
+  | { durationMs: number; outcome: 'timeout' }
+
+/**
+ * Map an outcome to its process exit code. Pure and total over the union so a
+ * driver's `case $?` stays exhaustive: 0 completed, 10 question/permission
+ * (worker is blocked and wants input), 3 the tab errored/exited, 124 we hit the
+ * overall cap.
+ */
+export function outcomeExitCode(outcome: RunOutcome): number {
+  switch (outcome.outcome) {
+    case 'completed':
+      return EXIT_OK
+    case 'question':
+      return EXIT_QUESTION
+    case 'error':
+      return EXIT_RUNTIME
+    case 'timeout':
+      return EXIT_TIMEOUT
+  }
+}
+
+/**
+ * Resolve the prompt text from exactly one source. We require exactly one of
+ * `--prompt-file`, `--stdin`, or the positional `[text]` so an orchestrator
+ * never silently sends the wrong buffer when two sources are set (e.g. a stale
+ * positional plus a fresh `--prompt-file`).
+ */
+async function resolvePromptText(
+  promptFile: string | undefined,
+  fromStdin: boolean,
+  positionalText: string | undefined
+): Promise<string> {
+  const sources = [promptFile !== undefined, fromStdin, positionalText !== undefined].filter(
+    (present) => present
+  ).length
+  if (sources !== 1) {
+    throw new Error(
+      'provide exactly one prompt source: --prompt-file <f>, --stdin, or a [text] positional'
+    )
+  }
+  if (promptFile !== undefined) return Bun.file(promptFile).text()
+  if (fromStdin) return Bun.stdin.text()
+  return positionalText ?? ''
+}
+
+export const tabRun: CliCommand = {
+  args: [{ name: 'tabId', required: true }, { name: 'text' }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
+    {
+      description: 'overall turn cap in milliseconds (default 900000 = 15 min)',
+      kind: 'number',
+      name: 'timeout',
+    },
+    {
+      description: 'stage the prompt without submitting (still waits)',
+      kind: 'boolean',
+      name: 'no-enter',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+
+    const promptFile =
+      typeof ctx.args.flags['prompt-file'] === 'string' ? ctx.args.flags['prompt-file'] : undefined
+    const fromStdin = ctx.args.flags.stdin === true
+    const text = await resolvePromptText(promptFile, fromStdin, ctx.args.positionals[1])
+
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
+    const appendEnter = ctx.args.flags['no-enter'] !== true
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (
+      !daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH) ||
+      !daemon.hasCapability(IPC_CAPABILITY_TURN_LIFECYCLE) ||
+      !daemon.hasCapability(IPC_CAPABILITY_QUESTION_EVENTS)
+    ) {
+      throw new Error(
+        'daemon predates tab run (turnLifecycle/questionEvents) — restart aimux to pick up the new daemon'
+      )
+    }
+
+    const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    if (!attach.tabs.some((t) => t.id === tabId)) {
+      throw new Error(`tab not found: ${tabId}`)
+    }
+
+    const payload = buildPromptPayload(text, false)
+
+    return new Promise<number>((resolve) => {
+      // Subscribe BEFORE writing: these events fire only on transitions, so a
+      // late subscription would race the worker starting its turn.
+      let start = Date.now()
+      // Uptake guard. The tab may sit `idle` from a prior turn; a stale
+      // `tabTurnComplete` (or the settle window closing on that old idle) must
+      // not read as "this turn completed". Only honour completion once we've
+      // seen the tab go `working` after our submit.
+      let sawWorking = false
+
+      const settle = (outcome: RunOutcome): void => {
+        cleanup()
+        writeJson(outcome)
+        resolve(outcomeExitCode(outcome))
+      }
+      const durationMs = (): number => Date.now() - start
+
+      const offStatus = daemon.on('tabStatus', (p) => {
+        if (p.tabId !== tabId) return
+        if (p.status === 'working') sawWorking = true
+      })
+      const offTurn = daemon.on('tabTurnComplete', (p) => {
+        if (p.tabId !== tabId) return
+        // Ignore end-of-turn until the worker actually started working, so a
+        // lingering pre-submit idle can't be mis-read as completion.
+        if (!sawWorking) return
+        settle({ durationMs: durationMs(), outcome: 'completed' })
+      })
+      const offQuestion = daemon.on('tabQuestion', (p) => {
+        if (p.tabId !== tabId) return
+        // A question is honoured immediately — it can legitimately arrive
+        // before `working` (the worker asks before doing anything).
+        settle({
+          durationMs: durationMs(),
+          kind: p.kind,
+          options: p.options,
+          outcome: 'question',
+          question: p.prompt,
+        })
+      })
+      const offExit = daemon.on('tabExit', (p) => {
+        if (p.tabId !== tabId) return
+        settle({ durationMs: durationMs(), error: `exit ${p.exitCode}`, outcome: 'error' })
+      })
+      const offError = daemon.on('tabError', (p) => {
+        if (p.tabId !== tabId) return
+        settle({ durationMs: durationMs(), error: p.message, outcome: 'error' })
+      })
+
+      const timer = setTimeout(() => {
+        settle({ durationMs: durationMs(), outcome: 'timeout' })
+      }, timeoutMs)
+
+      const cleanup = (): void => {
+        offStatus()
+        offTurn()
+        offQuestion()
+        offExit()
+        offError()
+        clearTimeout(timer)
+      }
+
+      // Submit after subscribing, then reset the clock so `durationMs` measures
+      // the worker's turn rather than our attach/write overhead. On a write
+      // failure the tab likely died — surface it as an error outcome rather
+      // than sitting idle until the timeout.
+      const submit = async (): Promise<void> => {
+        try {
+          await writePromptPayload(daemon, tabId, payload, appendEnter)
+          start = Date.now()
+        } catch (error) {
+          settle({
+            durationMs: durationMs(),
+            error: error instanceof Error ? error.message : String(error),
+            outcome: 'error',
+          })
+        }
+      }
+      void submit()
+    })
+  },
+  summary: 'Submit a prompt and block until the turn completes or the worker asks',
+  verb: 'run',
+}

package/src/cli/commands/tab/send.ts

@@ -1,33 +1,12 @@
 import type { CliCommand } from '../../registry'
 
 import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
-import { bracketedPaste, notationToBytes } from '../../chord'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
+import { buildPromptPayload, writePromptPayload } from './prompt-io'
 
-/**
- * Gap between the bracketed-paste write and the trailing carriage return when
- * `--enter` submits a pasted block. Claude Code (and other paste-aware TUIs)
- * buffer every byte between the paste-start/paste-end markers; a `\r` that
- * arrives in the same burst as the paste-end marker is folded into the paste
- * buffer as literal content instead of being read as a submit keystroke. A
- * short settle lets the receiver exit paste mode before the Enter lands.
- */
-const PASTE_SUBMIT_SETTLE_MS = 50
-
-/**
- * Lower a chord/paste buffer of bytes into the string the protocol expects.
- * Every byte we emit is < 0x80 (control chars or printable ASCII), so a
- * Latin-1 decode is faithful — the receiving PTY's UTF-8 path treats each
- * single byte as itself.
- */
-function bytesToString(bytes: Buffer): string {
-  let out = ''
-  for (const byte of bytes) {
-    out += String.fromCharCode(byte)
-  }
-  return out
-}
+/** Default ceiling for the submit→working transition under --await-submit. */
+const DEFAULT_AWAIT_TIMEOUT_MS = 15_000
 
 export const tabSend: CliCommand = {
   args: [{ name: 'tabId', required: true }, { name: 'text' }],
@@ -44,6 +23,18 @@ export const tabSend: CliCommand = {
       kind: 'boolean',
       name: 'stdin',
     },
+    {
+      description:
+        'after submitting, block until the tab transitions to working (uptake confirmed)',
+      kind: 'boolean',
+      name: 'await-submit',
+    },
+    {
+      description:
+        'milliseconds to wait for the working transition with --await-submit (default 15000)',
+      kind: 'number',
+      name: 'await-timeout',
+    },
   ],
   group: 'tab',
   run: async (ctx) => {
@@ -55,30 +46,25 @@ export const tabSend: CliCommand = {
     const fromStdin = ctx.args.flags.stdin === true
     const asKeys = ctx.args.flags.keys === true
     const appendEnter = ctx.args.flags.enter === true
+    const awaitSubmit = ctx.args.flags['await-submit'] === true
+    const awaitTimeoutMs =
+      typeof ctx.args.flags['await-timeout'] === 'number'
+        ? ctx.args.flags['await-timeout']
+        : DEFAULT_AWAIT_TIMEOUT_MS
 
-    let data: string
-    // Whether `data` is a bracketed-paste block (multi-line text that
-    // `bracketedPaste` wrapped in start/end markers). A trailing `\r` must be
-    // sent as a *separate*, settled write for these — see PASTE_SUBMIT_SETTLE_MS.
-    let bracketed = false
-    if (fromStdin) {
-      const stdinText = await Bun.stdin.text()
-      if (asKeys) {
-        data = bytesToString(notationToBytes(stdinText))
-      } else {
-        data = bracketedPaste(stdinText)
-        bracketed = data !== stdinText
-      }
-    } else {
-      const text = ctx.args.positionals[1] ?? ''
-      if (asKeys) {
-        if (text === '') throw new Error('--keys requires the chord notation as <text>')
-        data = bytesToString(notationToBytes(text))
-      } else {
-        data = bracketedPaste(text)
-        bracketed = data !== text
-      }
+    // Uptake only means something once we actually submit the prompt: the
+    // working transition is the receiving CLI accepting the Enter. Without
+    // --enter there is nothing to confirm, so fail loudly rather than block
+    // forever on a transition that can't come.
+    if (awaitSubmit && !appendEnter) {
+      throw new Error('--await-submit requires --enter')
+    }
+
+    const text = fromStdin ? await Bun.stdin.text() : (ctx.args.positionals[1] ?? '')
+    if (asKeys && text === '') {
+      throw new Error('--keys requires the chord notation as <text>')
     }
+    const payload = buildPromptPayload(text, asKeys)
 
     const workspace = ctx.getWorkspace()
     const daemon = await ctx.getDaemon()
@@ -89,22 +75,40 @@ export const tabSend: CliCommand = {
     }
 
     await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
-    await daemon.expectOk('write', { data, tabId })
 
-    let bytesWritten = Buffer.byteLength(data, 'utf8')
-    if (appendEnter) {
-      // A bracketed paste swallows a same-burst `\r`, so settle first, then
-      // submit as an independent write. Plain text / key chords carry no paste
-      // markers, so the Enter can follow immediately — but still as its own
-      // write so the two paths stay uniform.
-      if (bracketed) {
-        await Bun.sleep(PASTE_SUBMIT_SETTLE_MS)
-      }
-      await daemon.expectOk('write', { data: '\r', tabId })
-      bytesWritten += 1
+    if (!awaitSubmit) {
+      const bytesWritten = await writePromptPayload(daemon, tabId, payload, appendEnter)
+      writeJson({ bytesWritten, ok: true })
+      return EXIT_OK
     }
 
-    writeJson({ bytesWritten, ok: true })
+    // The daemon only emits tabStatus on TRANSITIONS, so we must be subscribed
+    // before the submit write lands — otherwise the working transition can fire
+    // between the write and our subscription and be lost forever. Arm the
+    // listener + a one-shot promise here, then start the clock right before the
+    // Enter so `ms` reflects submit→uptake latency, not setup overhead.
+    const uptake = new Promise<{ confirmed: true; ms: number } | { confirmed: false }>(
+      (resolve) => {
+        const off = daemon.on('tabStatus', (event) => {
+          if (event.tabId !== tabId || event.status !== 'working') return
+          off()
+          clearTimeout(timer)
+          resolve({ confirmed: true, ms: Date.now() - start })
+        })
+        const timer = setTimeout(() => {
+          off()
+          resolve({ confirmed: false })
+        }, awaitTimeoutMs)
+      }
+    )
+
+    const start = Date.now()
+    const bytesWritten = await writePromptPayload(daemon, tabId, payload, appendEnter)
+    const result = await uptake
+
+    // The bytes WERE written regardless of uptake — the working transition is
+    // advisory, so a missed transition is still EXIT_OK.
+    writeJson({ bytesWritten, ok: true, submitted: true, uptake: result })
     return EXIT_OK
   },
   summary: 'Write text or a key chord to a tab',

package/src/cli/index.ts

@@ -20,6 +20,7 @@ const EXIT_CODES_BLOCK = [
   '  2    usage error (bad flags, unknown command, missing argument)',
   '  3    runtime error (server replied with error, command failed)',
   '  4    daemon unreachable (socket missing and autostart failed)',
+  '  10   question (tab run: worker is blocked on a question/permission)',
   '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
 ].join('\n')
 

package/src/cli/output.ts

@@ -22,9 +22,11 @@ export function writeError(message: string): void {
 //   2   usage error (bad flags, unknown command, missing argument)
 //   3   runtime error (server replied with `error`, command failed)
 //   4   daemon unreachable (socket missing and autostart failed)
+//   10  question (`tab run`: worker is blocked on a question/permission)
 //   124 timeout (`tab wait`, `tab tail --timeout`, `workspace switch --wait`)
 export const EXIT_OK = 0
 export const EXIT_USAGE = 2
 export const EXIT_RUNTIME = 3
 export const EXIT_DAEMON_UNREACHABLE = 4
+export const EXIT_QUESTION = 10
 export const EXIT_TIMEOUT = 124

package/src/cli/registry.ts

@@ -5,6 +5,7 @@ import { tabClose } from './commands/tab/close'
 import { tabCreate } from './commands/tab/create'
 import { tabFocus } from './commands/tab/focus'
 import { tabList } from './commands/tab/list'
+import { tabRun } from './commands/tab/run'
 import { tabSend } from './commands/tab/send'
 import { tabSnapshot } from './commands/tab/snapshot'
 import { tabTail } from './commands/tab/tail'
@@ -31,6 +32,7 @@ export const COMMANDS: readonly CliCommand[] = [
   tabList,
   tabCreate,
   tabSend,
+  tabRun,
   tabFocus,
   tabClose,
   tabSnapshot,

package/src/daemon/daemon.ts

@@ -21,6 +21,7 @@ import {
 } from '../ipc/protocol'
 import { findSocketProcessPid, spawnDetachedTerminalManager } from '../platform/daemon-control'
 import { type LoopTabView, runStatusDetectionLoop } from '../pty/assistant-status-detection-loop'
+import { lastNonBlankLine } from '../pty/last-line'
 import { createDefaultTerminalModes } from '../state/terminal-modes'
 import { TerminalManagerClient } from '../terminal-manager/manager-client'
 import {
@@ -108,6 +109,18 @@ export function mergeTabRegistryEntry(
   return entry
 }
 
+/**
+ * Turn-complete settle window for the status loop, overridable via
+ * `AIMUX_TURN_SETTLE_MS` for slow/loaded machines. Falls back to the loop's
+ * own default when unset or non-numeric.
+ */
+function turnCompleteSettleMs(): number | undefined {
+  const raw = process.env.AIMUX_TURN_SETTLE_MS
+  if (raw == null || raw === '') return undefined
+  const parsed = Number(raw)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined
+}
+
 function send(socket: Socket, message: ServerResponse | ServerEvent): void {
   socket.write(encodeMessage(message))
 }
@@ -376,6 +389,20 @@ export async function runDaemon(): Promise<void> {
       logDebug('daemon.status.session', { sessionId, status })
       broadcastAll({ payload: { sessionId, status }, type: 'sessionStatus' })
     },
+    onTabQuestion: (tabId, sessionId, detail) => {
+      logDebug('daemon.status.question', { kind: detail.kind, sessionId, tabId })
+      // v13 / capability `questionEvents`. Same v13 send-time gate as below.
+      broadcastAllVersioned(13, {
+        payload: {
+          kind: detail.kind,
+          options: detail.options,
+          prompt: detail.prompt,
+          sessionId,
+          tabId,
+        },
+        type: 'tabQuestion',
+      })
+    },
     onTabStatus: (tabId, status, sessionId) => {
       logDebug('daemon.status.tab', { sessionId, status, tabId })
       // Broadcast to every client. Clients silently ignore events for tabIds
@@ -385,6 +412,14 @@ export async function runDaemon(): Promise<void> {
       // client tears down its socket to switch sessions.
       broadcastAll({ payload: { sessionId, status, tabId }, type: 'tabStatus' })
     },
+    onTurnComplete: (tabId, sessionId, idleMs) => {
+      logDebug('daemon.status.turnComplete', { idleMs, sessionId, tabId })
+      // v13 / capability `turnLifecycle`. Gate at send time — pre-v13 parsers
+      // throw on unknown event types and would drop the connection. MIN stays
+      // at 10, so we fan this only to peers that negotiated at least v13.
+      broadcastAllVersioned(13, { payload: { idleMs, sessionId, tabId }, type: 'tabTurnComplete' })
+    },
+    turnSettleMs: turnCompleteSettleMs(),
   })
 
   // Local HTTP server that receives Claude Code hook callbacks for every PTY
@@ -789,6 +824,12 @@ export async function runDaemon(): Promise<void> {
                       assistant: entry.assistant,
                       command: entry.command,
                       id: tabId,
+                      // Additive v13 field (capability `listTabsLastLine`): the
+                      // tab's last non-blank rendered line, so a fleet poll can
+                      // read "what each worker is doing" without a per-tab
+                      // snapshot. Undefined when the tab has no viewport yet, in
+                      // which case the field is omitted from the JSON wire.
+                      lastLine: lastNonBlankLine(entry.viewport),
                       status: entry.status ?? 'running',
                       title: entry.title ?? '',
                       worktreeId: entry.worktreeId,

package/src/ipc/protocol.ts

@@ -1,5 +1,6 @@
 import type {
   AssistantId,
+  QuestionKind,
   SessionStatus,
   TabActivity,
   TabSession,
@@ -29,8 +30,15 @@ import { isWorkspaceSnapshotV1, isWorktreeRecord } from '../state/validation'
 // `switchWorkspace`, `closeWorkspace`, `announceWorkspaceSwitched`) and
 // worktree record requests (`addWorktreeRecord`, `removeWorktreeRecord`),
 // plus matching broadcast events. All capability-gated; MIN stays at 10.
+//
+// v13: additive — agent-orchestration signals. Two new broadcast events,
+// `tabTurnComplete` (a tab's `idle` held long enough to call the turn done)
+// and `tabQuestion` (a tab entered `waiting-input`; carries the prompt text
+// plus best-effort parsed options), and an additive `lastLine` field on
+// `TabSessionSummary`. Gated behind `turnLifecycle`, `questionEvents`, and
+// `listTabsLastLine` respectively; MIN stays at 10.
 export const IPC_PROTOCOL_MIN_VERSION = 10
-export const IPC_PROTOCOL_VERSION = 12
+export const IPC_PROTOCOL_VERSION = 13
 
 /**
  * Capability advertised by a daemon that knows how to drain + handoff its
@@ -104,6 +112,31 @@ export const IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS = 'worktreeLifecycleEvents
  */
 export const IPC_CAPABILITY_TAB_TAIL = 'tabTail'
 
+/**
+ * v13 — capability gating the `tabTurnComplete` event. When advertised, the
+ * daemon broadcasts an authoritative end-of-turn signal once a tab's `idle`
+ * activity has held continuously for the settle window, so a driver need not
+ * poll `tabStatus` and re-confirm that idle held. Pre-cap peers never see the
+ * event and fall back to settle-polling `tabStatus`.
+ */
+export const IPC_CAPABILITY_TURN_LIFECYCLE = 'turnLifecycle'
+
+/**
+ * v13 — capability gating the `tabQuestion` event. When advertised, the daemon
+ * broadcasts the captured prompt text (plus best-effort parsed options) when a
+ * tab transitions into `waiting-input`, so a driver need not re-`snapshot` the
+ * screen and substring-match to learn what the worker is asking.
+ */
+export const IPC_CAPABILITY_QUESTION_EVENTS = 'questionEvents'
+
+/**
+ * v13 — capability gating the additive `lastLine` field on `listTabs`
+ * summaries. When advertised, each summary carries the tab's last non-blank
+ * rendered line so a fleet poll can read "what each worker is doing" without a
+ * `snapshot` round-trip per tab. Pre-cap daemons omit the field.
+ */
+export const IPC_CAPABILITY_LIST_TABS_LAST_LINE = 'listTabsLastLine'
+
 /**
  * Capabilities advertised by *this* process in its `helloResult`. Additive
  * features should be introduced as new capability strings here rather than
@@ -124,6 +157,9 @@ export const IPC_PROTOCOL_CAPABILITIES: readonly string[] = [
   IPC_CAPABILITY_WORKSPACE_LIFECYCLE,
   IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
   IPC_CAPABILITY_TAB_TAIL,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_LIST_TABS_LAST_LINE,
 ]
 
 export interface ProtocolHelloRequest {
@@ -184,6 +220,12 @@ export interface TabSessionSummary {
   activity?: TabActivity
   command: string
   worktreeId?: string
+  /**
+   * v13 / capability `listTabsLastLine`. The tab's last non-blank rendered
+   * line, trimmed. Present only when the daemon advertises the capability;
+   * omitted when the tab has produced no viewport yet.
+   */
+  lastLine?: string
 }
 
 export interface ListTabsResult {
@@ -324,6 +366,26 @@ export type ServerEvent =
   | { type: 'tabExit'; payload: { tabId: string; exitCode: number } }
   | { type: 'tabError'; payload: { tabId: string; message: string } }
   | { type: 'tabStatus'; payload: { sessionId: string; tabId: string; status: TabActivity } }
+  // v13 / capability `turnLifecycle`. Authoritative end-of-turn: broadcast
+  // once a tab's `idle` activity has held continuously for the settle window.
+  // Edge-triggered — re-armed only after the tab leaves `idle` again — so a
+  // driver gets exactly one per turn. `idleMs` is how long idle had held when
+  // the event fired.
+  | { type: 'tabTurnComplete'; payload: { sessionId: string; tabId: string; idleMs: number } }
+  // v13 / capability `questionEvents`. Broadcast when a tab transitions into
+  // `waiting-input`. `prompt` is the captured tail text (authoritative);
+  // `options` is a best-effort per-CLI parse of the choice list and may be
+  // absent even when the prompt clearly offers choices.
+  | {
+      type: 'tabQuestion'
+      payload: {
+        sessionId: string
+        tabId: string
+        kind: QuestionKind
+        prompt: string
+        options?: string[]
+      }
+    }
   | { type: 'sessionStatus'; payload: { sessionId: string; status: SessionStatus } }
   // Capability-gated on `tabLifecycleEvents`. Broadcast after a successful
   // `createTab` so every UI/CLI client attached to the same session learns
@@ -510,10 +572,15 @@ function isTabSessionSummary(value: unknown): value is TabSessionSummary {
       value.activity === 'waiting-input' ||
       value.activity === 'idle') &&
     isString(value.command) &&
-    (value.worktreeId === undefined || isString(value.worktreeId))
+    (value.worktreeId === undefined || isString(value.worktreeId)) &&
+    (value.lastLine === undefined || isString(value.lastLine))
   )
 }
 
+function isQuestionKind(value: unknown): value is QuestionKind {
+  return value === 'question' || value === 'permission'
+}
+
 function isListTabsResult(value: unknown): value is ListTabsResult {
   return (
     isObjectRecord(value) &&
@@ -786,6 +853,21 @@ export function parseServerMessage(value: unknown): ServerResponse | ServerEvent
       assert(isString(value.payload.tabId), 'tabStatus.tabId must be a string')
       assert(isTabActivity(value.payload.status), 'tabStatus.status is invalid')
       return value as ServerEvent
+    case 'tabTurnComplete':
+      assert(isString(value.payload.sessionId), 'tabTurnComplete.sessionId must be a string')
+      assert(isString(value.payload.tabId), 'tabTurnComplete.tabId must be a string')
+      assert(isFiniteNumber(value.payload.idleMs), 'tabTurnComplete.idleMs must be a number')
+      return value as ServerEvent
+    case 'tabQuestion':
+      assert(isString(value.payload.sessionId), 'tabQuestion.sessionId must be a string')
+      assert(isString(value.payload.tabId), 'tabQuestion.tabId must be a string')
+      assert(isQuestionKind(value.payload.kind), 'tabQuestion.kind is invalid')
+      assert(isString(value.payload.prompt), 'tabQuestion.prompt must be a string')
+      assert(
+        value.payload.options === undefined || isStringArray(value.payload.options),
+        'tabQuestion.options must be a string array when present'
+      )
+      return value as ServerEvent
     case 'tabAdded':
       assert(isString(value.payload.sessionId), 'tabAdded.sessionId must be a string')
       assert(isTabSession(value.payload.tab), 'tabAdded.tab is invalid')

package/src/pty/assistant-question-extractor.ts

@@ -0,0 +1,124 @@
+/**
+ * Question / permission extraction.
+ *
+ * When a tab transitions into `waiting-input`, the status detection loop calls
+ * this to turn "the worker is blocked" into a structured event: what it's
+ * asking (the captured prompt text — authoritative) plus a best-effort parse
+ * of the choice list. It reuses the detector's tail extraction so both read
+ * the screen identically.
+ *
+ * Option parsing is explicitly best-effort and per-CLI: TUIs render menus in
+ * shapes that shift between versions. `prompt` is always populated; `options`
+ * may be absent even when the screen clearly offers choices. Consumers should
+ * treat `prompt` as the source of truth and `options` as a convenience.
+ */
+import type { AssistantId, QuestionKind, TerminalSnapshot } from '../state/types'
+
+import { extractTailLines } from './assistant-status-detector'
+
+/** How many trailing non-blank lines to capture as the prompt text. Wider than
+ *  the 10-line classification tail so a multi-line permission block or a long
+ *  question is captured whole. */
+const PROMPT_TAIL_LINES = 20
+
+export interface QuestionDetail {
+  kind: QuestionKind
+  /** The captured waiting-input tail, trailing-trimmed, joined with newlines. */
+  prompt: string
+  /** Best-effort parsed choice list; omitted when none could be recognised. */
+  options?: string[]
+}
+
+/**
+ * Substrings that mark a blocked prompt as a permission / approval request
+ * rather than a free-form question. Lower-cased haystack match. Kept broad and
+ * shared across CLIs; per-CLI extras are folded in below.
+ */
+const PERMISSION_SIGNALS: readonly string[] = [
+  'do you want',
+  'permission required',
+  'permission to',
+  '△ permission',
+  'allow this',
+  'approve',
+  'grant',
+  'press enter to confirm',
+]
+
+/**
+ * Extract the structured question for a tab already classified as
+ * `waiting-input`. Returns null only when there's no viewport / no text to
+ * report; otherwise `prompt` is always present.
+ */
+export function extractQuestion(
+  assistant: AssistantId,
+  viewport: TerminalSnapshot | undefined
+): QuestionDetail | null {
+  if (!viewport) return null
+  const lines = extractTailLines(viewport, PROMPT_TAIL_LINES)
+  if (lines.length === 0) return null
+
+  const prompt = lines.join('\n')
+  const haystack = prompt.toLowerCase()
+  const kind = detectKind(assistant, haystack)
+  const options = parseOptions(lines, haystack)
+  return options ? { kind, options, prompt } : { kind, prompt }
+}
+
+function detectKind(assistant: AssistantId, haystack: string): QuestionKind {
+  for (const signal of PERMISSION_SIGNALS) {
+    if (haystack.includes(signal)) return 'permission'
+  }
+  // opencode surfaces tool approvals under a "permission" banner; codex uses an
+  // approval confirm. Both already covered by the shared signals, but keep the
+  // assistant param so future per-CLI divergence has a seam.
+  void assistant
+  return 'question'
+}
+
+/**
+ * Matches a numbered menu row: an optional selection marker (❯ › > *), a digit,
+ * a `.`/`)` separator, then the option label. Capturing the label lets us strip
+ * the marker/number so consumers get clean text.
+ */
+const NUMBERED_OPTION = /^\s*[❯›>*]?\s*\d+[.)]\s+(\S.*)$/u
+
+/**
+ * Matches an arrow-selected label with no number, e.g. Claude's `❯ Yes` /
+ * `  No` yes-no menus.
+ */
+const MARKED_OPTION = /^\s*[❯›]\s+(\S.*)$/u
+
+function parseOptions(lines: readonly string[], haystack: string): string[] | undefined {
+  const numbered: string[] = []
+  for (const line of lines) {
+    const captured = NUMBERED_OPTION.exec(line)?.[1]
+    if (captured != null && captured !== '') numbered.push(captured.trimEnd())
+  }
+  if (numbered.length >= 2) return numbered
+
+  // No numbered menu — look for a single arrow-marked choice paired with its
+  // siblings is unreliable, so fall back to explicit yes/no affordances.
+  if (
+    haystack.includes('[y/n]') ||
+    haystack.includes('(y/n)') ||
+    haystack.includes('yes/no') ||
+    haystack.includes('y/n?')
+  ) {
+    return ['Yes', 'No']
+  }
+
+  const marked = lines.map((line) => MARKED_OPTION.exec(line)?.[1]?.trimEnd()).filter(isNonEmpty)
+  if (marked.length >= 1 && numbered.length === 0) {
+    // A lone highlighted option (e.g. a confirm dialog defaulting to Yes) — only
+    // surface it when it's a short label, not a highlighted sentence.
+    const short = marked.filter((label) => label.length <= 40)
+    if (short.length >= 1) return short
+  }
+
+  return undefined
+}
+
+function isNonEmpty(value: string | undefined): value is string {
+  return value !== undefined && value.length > 0
+}

package/src/pty/assistant-status-detection-loop.ts

@@ -17,6 +17,7 @@ import type { AssistantId, SessionStatus, TabActivity, TerminalSnapshot } from '
 
 import { logDebug } from '../debug/input-log'
 import { getLineText } from '../input/terminal-text-extraction'
+import { extractQuestion } from './assistant-question-extractor'
 import { AssistantStatusArbiter, type RecordHookEventInput } from './assistant-status-arbiter'
 import { AssistantStatusDetector } from './assistant-status-detector'
 
@@ -35,6 +36,15 @@ function tailPreview(viewport: TerminalSnapshot | undefined): string {
 /** Default polling interval. Cheap — detector is a handful of substring checks. */
 const DEFAULT_TICK_MS = 500
 
+/**
+ * How long a tab's `idle` activity must hold continuously before we call the
+ * turn complete. `idle` can flash for a fraction of a second between two tool
+ * calls, so an end-of-turn signal that fired on the first idle tick would catch
+ * the worker mid-turn. Requiring idle to *hold* this long is the authoritative
+ * replacement for a driver's settle-poll loop.
+ */
+const DEFAULT_TURN_SETTLE_MS = 1500
+
 export interface LoopTabView {
   id: string
   assistant: AssistantId
@@ -49,7 +59,30 @@ export interface StatusDetectionLoopOptions {
   onTabStatus: (tabId: string, status: TabActivity, sessionId: string) => void
   /** Emitted when either flag on a session changes. */
   onSessionStatus: (sessionId: string, status: SessionStatus) => void
+  /**
+   * Emitted once per turn, when a tab's `idle` activity has held continuously
+   * for `turnSettleMs`. Edge-triggered: re-armed only after the tab leaves
+   * `idle`, so a driver receives exactly one signal per turn. `idleMs` is how
+   * long idle had held when the signal fired.
+   */
+  onTurnComplete?: (tabId: string, sessionId: string, idleMs: number) => void
+  /**
+   * Emitted when a tab transitions into `waiting-input`. Edge-triggered: fires
+   * once per transition, carrying the captured prompt text and any parsed
+   * options. Fires on both tick and attach replay so a client that attaches to
+   * an already-blocked tab still learns the question.
+   */
+  onTabQuestion?: (
+    tabId: string,
+    sessionId: string,
+    detail: { kind: 'question' | 'permission'; prompt: string; options?: string[] }
+  ) => void
   tickMs?: number
+  /** Override the turn-complete settle window (default 1500ms). */
+  turnSettleMs?: number
+  /** Override the clock. Defaults to Date.now. Tests inject a logical clock so
+   *  the wall-clock-driven turn-complete settle is deterministic. */
+  nowFn?: () => number
 }
 
 export interface StatusDetectionLoopHandle {
@@ -80,10 +113,18 @@ export function runStatusDetectionLoop(
   options: StatusDetectionLoopOptions
 ): StatusDetectionLoopHandle {
   const tickMs = options.tickMs ?? DEFAULT_TICK_MS
+  const turnSettleMs = options.turnSettleMs ?? DEFAULT_TURN_SETTLE_MS
+  const now = options.nowFn ?? Date.now
   const detector = new AssistantStatusDetector()
   const arbiter = new AssistantStatusArbiter()
   const lastTabStatus = new Map<string, { status: TabActivity; sessionId: string }>()
   const lastSessionStatus = new Map<string, SessionStatus>()
+  // Timestamp when a tab most recently entered `idle`. Cleared when it leaves
+  // idle. `turnEmitted` guards against re-firing `onTurnComplete` within the
+  // same idle episode; it's cleared alongside `idleSince` so the next turn
+  // re-arms.
+  const idleSince = new Map<string, number>()
+  const turnEmitted = new Set<string>()
 
   const timer = setInterval(() => {
     try {
@@ -134,6 +175,38 @@ export function runStatusDetectionLoop(
         lastTabStatus.set(tab.id, { sessionId, status })
         options.onTabStatus(tab.id, status, sessionId)
       }
+
+      // Turn-complete bookkeeping. The emission itself is gated to `tick` so a
+      // synchronous attach replay (`classifyNow`) never fabricates an
+      // end-of-turn — only the wall-clock-driven poll does. The idleSince /
+      // turnEmitted maps are maintained on every call so state stays coherent
+      // regardless of source.
+      if (status === 'idle') {
+        let since = idleSince.get(tab.id)
+        if (since === undefined) {
+          since = now
+          idleSince.set(tab.id, since)
+        }
+        if (source === 'tick' && !turnEmitted.has(tab.id) && now - since >= turnSettleMs) {
+          turnEmitted.add(tab.id)
+          options.onTurnComplete?.(tab.id, sessionId, now - since)
+        }
+      } else {
+        idleSince.delete(tab.id)
+        turnEmitted.delete(tab.id)
+      }
+
+      // Question extraction on the idle/working → waiting-input edge. `prev`
+      // still holds the pre-update status, so this fires exactly once per
+      // transition even though the loop broadcasts to every client.
+      if (
+        status === 'waiting-input' &&
+        (!prev || prev.status !== 'waiting-input') &&
+        options.onTabQuestion
+      ) {
+        const detail = extractQuestion(tab.assistant, tab.viewport)
+        if (detail) options.onTabQuestion(tab.id, sessionId, detail)
+      }
     }
     const next: SessionStatus = { waiting, working }
     const prevSession = lastSessionStatus.get(sessionId)
@@ -154,14 +227,14 @@ export function runStatusDetectionLoop(
   }
 
   function tick(): void {
-    const now = Date.now()
+    const ts = now()
     const sessionIds = options.listSessions()
     const seenSessions = new Set<string>()
     const seenTabs = new Set<string>()
 
     for (const sessionId of sessionIds) {
       seenSessions.add(sessionId)
-      classifySession(sessionId, options.listTabs(sessionId), now, 'tick', seenTabs)
+      classifySession(sessionId, options.listTabs(sessionId), ts, 'tick', seenTabs)
     }
 
     for (const tabId of lastTabStatus.keys()) {
@@ -169,6 +242,8 @@ export function runStatusDetectionLoop(
         detector.forget(tabId)
         arbiter.forget(tabId)
         lastTabStatus.delete(tabId)
+        idleSince.delete(tabId)
+        turnEmitted.delete(tabId)
       }
     }
     for (const sessionId of lastSessionStatus.keys()) {
@@ -180,7 +255,7 @@ export function runStatusDetectionLoop(
 
   return {
     classifyNow: (sessionId, tabs) => {
-      classifySession(sessionId, tabs, Date.now(), 'classifyNow')
+      classifySession(sessionId, tabs, now(), 'classifyNow')
     },
     getSessionStatus: (sessionId) => lastSessionStatus.get(sessionId),
     getTabStatus: (tabId) => lastTabStatus.get(tabId)?.status,
@@ -206,6 +281,8 @@ export function runStatusDetectionLoop(
       arbiter.clear()
       lastTabStatus.clear()
       lastSessionStatus.clear()
+      idleSince.clear()
+      turnEmitted.clear()
     },
   }
 }

package/src/pty/assistant-status-detector.ts

@@ -85,7 +85,14 @@ export class AssistantStatusDetector {
   }
 }
 
-function extractTailText(viewport: TerminalSnapshot, lineCount: number): string {
+/**
+ * Last `lineCount` non-blank rendered lines, trailing-trimmed, oldest-first.
+ * Shared by the status detector (10-line tail for classification) and the
+ * question extractor (larger tail for prompt capture) so both read the screen
+ * the same way. Prefers `tailLines` when the user has scrolled the viewport
+ * off the active screen.
+ */
+export function extractTailLines(viewport: TerminalSnapshot, lineCount: number): string[] {
   const isScrolledToBottom = viewport.viewportY === viewport.baseY
   const lines = isScrolledToBottom ? viewport.lines : (viewport.tailLines ?? viewport.lines)
   // Full-screen TUIs (claude, opencode) paint in the alternate buffer and
@@ -112,7 +119,11 @@ function extractTailText(viewport: TerminalSnapshot, lineCount: number): string
     if (!line) continue
     parts.push(getLineText(line).replace(/\s+$/u, ''))
   }
-  return parts.join('\n')
+  return parts
+}
+
+function extractTailText(viewport: TerminalSnapshot, lineCount: number): string {
+  return extractTailLines(viewport, lineCount).join('\n')
 }
 
 function classifyBuiltin(

package/src/pty/last-line.ts

@@ -0,0 +1,29 @@
+/**
+ * Extract a terminal viewport's last non-blank rendered line.
+ *
+ * Used by the daemon's `listTabs` handler to answer "what is this worker
+ * doing?" without a per-tab `snapshot` round-trip. Unlike the status loop's
+ * private `tailPreview`, this does NOT cap the width — the orchestrator wants
+ * the whole status line — and it returns `undefined` (rather than a sentinel)
+ * when there is nothing to show, so the field is simply omitted from the wire.
+ */
+import type { TerminalSnapshot } from '../state/types'
+
+import { getLineText } from '../input/terminal-text-extraction'
+
+/**
+ * The last non-blank line of `viewport`, trimmed. Scans rows from the bottom so
+ * trailing blank rows are skipped. Returns `undefined` when the viewport is
+ * missing or entirely blank.
+ */
+export function lastNonBlankLine(viewport: TerminalSnapshot | undefined): string | undefined {
+  if (!viewport) return undefined
+  const lines = viewport.lines
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line) continue
+    const text = getLineText(line).trim()
+    if (text.length > 0) return text
+  }
+  return undefined
+}

package/src/session-backend/remote-session-backend.ts

@@ -192,6 +192,11 @@ export class RemoteSessionBackend
         })
         this.emit('tabActivity', message.payload.tabId, message.payload.status)
         break
+      case 'tabTurnComplete':
+      case 'tabQuestion':
+        // v13 orchestration signals — consumed by the headless CLI, not the UI
+        // backend. Enumerated so the switch stays exhaustive; no UI wiring yet.
+        break
       case 'sessionStatus':
         logDebug('backend.remote.sessionStatus', {
           sessionId: message.payload.sessionId,

package/src/state/types.ts

@@ -18,6 +18,14 @@ export type LegacyPersistedTabStatus = TabStatus | 'exited'
 
 export type TabActivity = 'working' | 'waiting-input' | 'idle'
 
+/**
+ * Classifies why a tab is blocked on user input. `permission` is a tool /
+ * command approval prompt; `question` is any other prompt the assistant is
+ * waiting on. Carried by the `tabQuestion` server event so an orchestrator can
+ * branch without re-scraping the screen.
+ */
+export type QuestionKind = 'question' | 'permission'
+
 /**
  * Per-session status flags. Both can be true at once (e.g. one tab working,
  * another waiting for user input) so we keep them as independent booleans