Merge origin/master (generic task runtime #219, single-exe closure, package renames)

Semantic resolutions beyond line merges: - The bash seam keeps resolveMode + the bash/resolve-mode waterfall on master's task-free BashExecutor (run/start/resolve only; BashProcess handles); tool-bash consults it at its stamping site and escalation baseline on master's render/background split, with a waterfall test on the recording executor. - dsh-mode's BASH_FAMILY narrows to ['bash']: bash_output/bash_kill are replaced by the kind-generic task_output/task_kill, which span every task kind and only observe or stop work, so the access cap withholds only the starter it can reason about. - The plan-mode snapshot suite adopts master's pin grammar (tool-schema sidecars; the expectedHeaderSnapshots extension is gone — the exit transition deltas, and entering-before-turn-1 needs no second snapshot); modes-advertise joins the plan header class (no-model, so membership is vacuous). Fixtures re-recorded on the acp-demo bin; the replay overlay gains the passthrough sandbox runner. - examples/plan-acp-agent rewires to @deepseek-ai/dsh-acp-demo and drops its tool-bash entry (the spine bundle now composes it); dsh-stdio (the renamed stdio-chat home) keeps its /mode command and gains the dsh-mode peer edge; the acp bridge keeps the modes surface beside master's permission presets. - mode README gains the Model Experience / Known Limitations sections the new README gates require; AGENTS.md ceiling 1370 → 1440 for the kept mode/ layout line and Agent efficiency section.
2026-07-15 23:17:18 +08:00
parent 85a2140781 4b11e420d9
commit 1f38b211be
935 changed files with 27831 additions and 21211 deletions
--- a/packages/ui/stdio/README.md
+++ b/packages/ui/stdio/README.md
@@ -0,0 +1,42 @@
+# @deepseek-ai/dsh-stdio
+
+The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal.
+
+This package owns the terminal channel only. It injects `agents` and `userInteraction`, then drives an agent created or resumed by app or developer code. The agent spine, agent lifecycle, console logger, and model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `welcome` | `ready.` | Banner printed before the first prompt |
+| `agent` | `main` | Agent id driven by stdin and observed for EOF shutdown |
+
+The plugin seeds display labels from the live agent registry, then tracks `agent/created` and `agent/disposed` so HMR and externally managed agents render consistently. Disposal closes readline and unregisters every listener/provider through Cordis effects.
+
+```yaml
+- id: stdio
+  name: '@deepseek-ai/dsh-stdio'
+  config:
+    welcome: 'agent REPL ready. Give it a coding task.'
+    agent: main
+```
+
+## Model Experience
+
+### Readline prompt input
+
+**What the model sees**: Each non-empty terminal line outside an active question becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running.
+
+**Token effect**: Submitted text is retained under the agent loop's normal session-history and compaction rules. The welcome banner, `> ` prompt, rendered transcript, and `[tool call]` / `[tool result]` terminal lines add no tokens.
+
+### Terminal user-interaction answers
+
+**What the model sees**: When a consumer calls `ctx.userInteraction.ask()`, this provider renders the question in the terminal and returns selected option labels or `custom` text. Through `dsh-tool-ask-user`, closed stdin becomes `Error: ask_user_question cannot be answered because stdin is closed`; disposal or abort becomes `Error: ask_user_question was interrupted before the user answered`.
+
+**Token effect**: Waiting and terminal prompts add no tokens; the resolved answer or error is model-visible only through the calling tool or plugin's result.
+
+## Known Limitations and Deferred Work
+
+- **One configured agent receives stdin** — the session/event renderer can print output from any session, but input lines always drive the configured `agent` id rather than routing by the visible label.
+- **Terminal questions are text-only and sequential** — the provider queues asks, supports option labels plus custom text, and has no richer UI shapes such as file pickers or diff previews.
+- **Closed stdin ends the terminal channel** — EOF rejects active or queued questions and exits after submitted work reaches idle; there is no reconnect path for a long-lived process.
--- a/packages/ui/stdio/package.json
+++ b/packages/ui/stdio/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-stdio",
+  "description": "Terminal readline front door for driving and rendering DeepSeek Harness agents over stdio",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-mode": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-mode": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/ui/stdio/src/index.ts
+++ b/packages/ui/stdio/src/index.ts
@@ -0,0 +1,430 @@
+/**
+ * The stdio app's readline UI: reads lines from stdin into `agent.send()` or
+ * `steer()`, renders the durable event stream to stdout, and exits piped input
+ * only after submitted work reaches idle.
+ *
+ * This package is the independently composable stdio front door. It establishes
+ * the terminal channel and drives an agent created or resumed by app or
+ * developer code.
+ * @module @deepseek-ai/dsh-stdio
+ */
+
+import { createInterface } from 'node:readline'
+import type { Readable, Writable } from 'node:stream'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import {
+  UserInteractionError,
+  type AskUserQuestionAnswer,
+  type AskUserQuestionAnswerItem,
+  type AskUserQuestionItem,
+  type AskUserQuestionOption,
+  type AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-interaction'
+// Type-only edge: makes `ctx.get('modes')` resolve the ModesService type when
+// @deepseek-ai/dsh-mode is composed; the runtime read stays opportunistic.
+import type {} from '@deepseek-ai/dsh-mode'
+
+export const name = 'ui-stdio'
+export const inject = ['agents', 'userInteraction']
+
+/** Serializable plugin configuration (cordis-native, schemastery). */
+export interface Config {
+  /** Banner printed once on start, before the first `> ` prompt. */
+  welcome?: string
+  /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
+  agent?: string
+}
+
+export const Config: z<Config> = z.object({
+  welcome: z.string().default('ready.'),
+  agent: z.string().default('main'),
+})
+
+/**
+ * Process-I/O seam — the side-effecting handles the plugin would otherwise
+ * reach for as globals. Defaulted to the real `process` streams in
+ * {@link apply}; injected by tests so the EOF, render, and disposal branches
+ * are exercised without hijacking globals. Deliberately NOT part of the
+ * serializable {@link Config} (streams/functions don't belong in YAML config).
+ */
+export interface StdioRuntime {
+  /** Line source (default `process.stdin`). */
+  input: Readable
+  /** Render sink (default `process.stdout`). */
+  output: Writable
+  /** Process-exit hook (default `process.exit`); called once on stdin EOF. */
+  exit: (code: number) => void
+}
+
+function isTTYPair(input: Readable, output: Writable): boolean {
+  return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY)
+}
+
+interface PendingQuestion {
+  request: AskUserQuestionRequest
+  questionIndex: number
+  answers: AskUserQuestionAnswerItem[]
+  resolve(answer: AskUserQuestionAnswer): void
+  reject(error: unknown): void
+  onAbort: () => void
+}
+
+type OptionSelection =
+  | { kind: 'selected'; options: AskUserQuestionOption[] }
+  | { kind: 'custom' }
+  | { kind: 'invalid' }
+
+/**
+ * Register stdio chat against an injectable I/O runtime.
+ * @param ctx - agent and event context.
+ * @param config - plugin config, defaulted for direct callers.
+ * @param runtime - line source, render sink, and exit hook.
+ */
+export function createStdioChat(ctx: Context, config: Config, runtime: StdioRuntime): void {
+  // Default here too (not just via schemastery's `.default()`): this helper is
+  // exported and called directly by tests / programmatic consumers that bypass
+  // Loader validation, so it must be self-contained rather than trusting the
+  // cast — `config.welcome as string` would otherwise be `undefined` on `{}`.
+  const welcome = config.welcome ?? 'ready.'
+  const agentId = AgentId(config.agent ?? 'main')
+  const { input, output, exit } = runtime
+
+  // Session ids need not equal agent ids. Seed existing agents before listening
+  // so a pre-created or HMR-surviving agent still gets its short render label.
+  const labelBySession = new Map<string, string>()
+  for (const agent of ctx.agents.list()) labelBySession.set(agent.session.header.id, agent.id)
+  ctx.on('agent/created', (agent) => { labelBySession.set(agent.session.header.id, agent.id) })
+  ctx.on('agent/disposed', (agent) => { labelBySession.delete(agent.session.header.id) })
+
+  // Render the canonical append order from session/event so reasoning state is
+  // deterministic across chunks and boundaries; there are no agent/* mirrors.
+  let inReasoning = false
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'assistant/chunk') {
+      const { chunk } = event.data
+      if (chunk.type === 'reasoning-delta') {
+        // Dim the chain-of-thought so the final answer stands out.
+        if (!inReasoning) output.write('\x1B[2m')
+        inReasoning = true
+        output.write(chunk.text)
+      } else if (chunk.type === 'text-delta') {
+        if (inReasoning) output.write('\x1B[0m\n')
+        inReasoning = false
+        output.write(chunk.text)
+      }
+    } else if (event.type === 'turn/start') {
+      const label = labelBySession.get(session.header.id) ?? session.header.id
+      output.write(`\n[${label} turn ${event.data.turn}] `)
+    } else if (event.type === 'turn/end') {
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      output.write('\n> ')
+    } else if (event.type === 'tool/call') {
+      const { name: toolName, arguments: args } = event.data
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      output.write(`\n  [tool call] ${toolName}(${args})`)
+    } else if (event.type === 'tool/result') {
+      const { content } = event.data
+      const text = content.filter(block => block.type === 'text').map(block => block.text).join('')
+      output.write(`\n  [tool result] ${text}\n  `)
+    } else if (event.type === 'todo/write') {
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      const glyph = (status: string): string =>
+        status === 'completed' ? '[x]' : status === 'in_progress' ? '[~]' : '[ ]'
+      const lines = event.data.todos.map(todo => `    ${glyph(todo.status)} ${todo.content}`).join('\n')
+      output.write(`\n  [todos]\n${lines}\n  `)
+    }
+  })
+
+  ctx.effect(() => {
+    const reader = createInterface({ input, output, terminal: isTTYPair(input, output) })
+    // On piped EOF, exit immediately if no work was submitted. Otherwise wait
+    // for a real running state followed by idle: sends do not synchronously mark
+    // running, and several queued lines may share one turn.
+    let stdinClosed = false
+    let disposed = false
+    let submittedWork = false
+    let sawRunning = false
+    let exitTimer: ReturnType<typeof setTimeout> | undefined
+    let activeQuestion: PendingQuestion | undefined
+    const questionQueue: PendingQuestion[] = []
+
+    const maybeExit = (): void => {
+      if (disposed || !stdinClosed) return
+      // No work submitted: nothing will ever run, exit straight away.
+      // Work submitted: wait until a turn has run and the agent is idle.
+      if (submittedWork) {
+        if (!sawRunning) return
+        const agent = ctx.agents.get(agentId)
+        if (agent && agent.status !== 'idle') return // a turn is still running
+      }
+      // Let final output flush; track the timer so re-entry coalesces and HMR
+      // disposal can cancel it before it exits the replacement process.
+      if (exitTimer !== undefined) {
+        return // exit already scheduled — coalesce re-entrant calls
+      }
+      exitTimer = setTimeout(() => { exit(0) }, 200)
+    }
+
+    const disposeStatusListener = ctx.on('agent/status', (subject, status) => {
+      if (subject.id !== agentId) return
+      if (status === 'running') sawRunning = true
+      if (status === 'idle') maybeExit()
+    })
+
+    const activeQuestionItem = (pending: PendingQuestion): AskUserQuestionItem =>
+      pending.request.questions[pending.questionIndex] as AskUserQuestionItem
+
+    const renderQuestion = (pending: PendingQuestion): void => {
+      const question = activeQuestionItem(pending)
+      const options = question.options ?? []
+      output.write('\n')
+      output.write(question.header ? `[${question.header}] ${question.question}\n` : `${question.question}\n`)
+      options.forEach((option, index) => {
+        output.write(`  ${index + 1}. ${option.label}\n`)
+        if (option.description) output.write(`     ${option.description}\n`)
+      })
+      output.write('> ')
+    }
+
+    const removeAbortListener = (pending: PendingQuestion): void => {
+      pending.request.signal?.removeEventListener('abort', pending.onAbort)
+    }
+
+    const startNextQuestion = (): void => {
+      if (activeQuestion !== undefined) return
+      const pending = questionQueue.shift()
+      if (pending === undefined) return
+      // The queue never contains an aborted pending ask: the seam rejects an
+      // already-aborted request synchronously, and queued asks attach their
+      // abort listener before enqueueing.
+      activeQuestion = pending
+      renderQuestion(pending)
+    }
+
+    const disposeQuestion = (pending: PendingQuestion): void => {
+      removeAbortListener(pending)
+      pending.reject(new UserInteractionError('ask_user_question was interrupted before the user answered', 'ASK_ABORTED'))
+    }
+
+    const disposePendingQuestions = (): void => {
+      if (activeQuestion !== undefined) {
+        disposeQuestion(activeQuestion)
+        activeQuestion = undefined
+      }
+      for (const pending of questionQueue.splice(0)) {
+        disposeQuestion(pending)
+      }
+    }
+
+    const finishQuestion = (pending: PendingQuestion): void => {
+      activeQuestion = undefined
+      removeAbortListener(pending)
+      pending.resolve({ answers: pending.answers })
+      output.write('\n')
+      startNextQuestion()
+    }
+
+    const answerCurrentQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswerItem): void => {
+      pending.answers.push(answer)
+      pending.questionIndex += 1
+      if (pending.questionIndex >= pending.request.questions.length) {
+        finishQuestion(pending)
+        return
+      }
+      renderQuestion(pending)
+    }
+
+    const selectedOptions = (text: string, options: AskUserQuestionOption[], multiSelect: boolean): OptionSelection => {
+      if (text === '') return { kind: 'invalid' }
+      if (!multiSelect) {
+        if (!/^\d+$/.test(text)) return { kind: 'custom' }
+        const selected = options[Number(text) - 1]
+        return selected === undefined ? { kind: 'invalid' } : { kind: 'selected', options: [selected] }
+      }
+      const indices = text.split(/[,\s]+/).filter(Boolean)
+      if (indices.length === 0) return { kind: 'invalid' }
+      if (indices.some(part => !/^\d+$/.test(part))) return { kind: 'custom' }
+      const uniqueIndices = [...new Set(indices)]
+      const selected = uniqueIndices.map(part => options[Number(part) - 1])
+      return selected.some(option => option === undefined)
+        ? { kind: 'invalid' }
+        : { kind: 'selected', options: selected as AskUserQuestionOption[] }
+    }
+
+    const answerQuestion = (line: string): void => {
+      const pending = activeQuestion as PendingQuestion
+      const question = activeQuestionItem(pending)
+
+      const text = line.trim()
+      const options = question.options ?? []
+      const selection = options.length > 0
+        ? selectedOptions(text, options, question.multiSelect ?? false)
+        : { kind: text === '' ? 'invalid' : 'custom' } as OptionSelection
+      if (selection.kind === 'selected') {
+        answerCurrentQuestion(pending, { id: question.id, selected: selection.options.map(option => option.label) })
+        return
+      }
+
+      if (selection.kind === 'custom' && text !== '') {
+        answerCurrentQuestion(pending, { id: question.id, selected: [], custom: text })
+        return
+      }
+
+      output.write(options.length > 0
+        ? 'Please enter one of the option numbers'
+          + (question.multiSelect ? ' (comma or space separated)' : '')
+          + ' or a custom answer'
+          + '.\n> '
+        : 'Please enter an answer.\n> ')
+    }
+
+    const disposeUserInteractionProvider = ctx.userInteraction.registerProvider({
+      ask(request) {
+        if (disposed || stdinClosed) {
+          return Promise.reject(
+            new UserInteractionError('ask_user_question cannot be answered because stdin is closed', 'ASK_ABORTED'),
+          )
+        }
+        return new Promise<AskUserQuestionAnswer>((resolve, reject) => {
+          const pending: PendingQuestion = {
+            request,
+            questionIndex: 0,
+            answers: [],
+            resolve,
+            reject,
+            onAbort: () => {
+              if (activeQuestion === pending) {
+                activeQuestion = undefined
+                disposeQuestion(pending)
+                startNextQuestion()
+                return
+              }
+              // If it is not active, this listener can only fire while the ask
+              // remains queued; settled asks remove the listener first.
+              questionQueue.splice(questionQueue.indexOf(pending), 1)
+              disposeQuestion(pending)
+            },
+          }
+          request.signal?.addEventListener('abort', pending.onAbort, { once: true })
+          questionQueue.push(pending)
+          startNextQuestion()
+        })
+      },
+    })
+
+    reader.on('line', (line) => {
+      const text = line.trim()
+      if (text === '/mode' || text.startsWith('/mode ')) {
+        // A command line, never sent to the model — and reserved even while a
+        // question prompt is active: a command swallowed as a free-text answer
+        // would land in the tool result as model-visible feedback (the plan
+        // review is exactly such a prompt), so command handling runs before
+        // answer dispatch. The switch is a pending intent the mode service
+        // flushes at the next turn boundary (dsh-mode's turn-enclosure
+        // contract); an active question stays pending and still owns the
+        // next non-command line.
+        const agent = ctx.agents.get(agentId)
+        if (!agent) {
+          ctx.logger.error('ui-stdio: agent "%s" is not running', agentId)
+          return
+        }
+        const modes = ctx.get('modes')
+        if (modes === undefined) {
+          output.write('session modes are not composed in this deployment\n> ')
+          return
+        }
+        const target = text.slice('/mode'.length).trim()
+        if (target === '') {
+          const { current, pending } = modes.get(agent)
+          const pendingNote = pending === undefined ? '' : ` (pending: ${pending})`
+          output.write(`mode: ${current}${pendingNote} — available: ${modes.list().join(', ')}\n> `)
+          return
+        }
+        try {
+          modes.set(agent, target)
+          output.write(`mode → ${target} (applies from the next turn)\n> `)
+        } catch (error) {
+          // ModesService.set throws only Error (its unknown-name validation).
+          output.write(`${(error as Error).message}\n> `)
+        }
+        return
+      }
+      if (activeQuestion !== undefined) {
+        answerQuestion(line)
+        return
+      }
+      if (!text) return
+      const agent = ctx.agents.get(agentId)
+      if (!agent) {
+        ctx.logger.error('ui-stdio: agent "%s" is not running', agentId)
+        return
+      }
+      submittedWork = true
+      if (agent.status === 'running') {
+        agent.steer([{ type: 'text', text }])
+      } else {
+        agent.send([{ type: 'text', text }])
+      }
+    })
+    reader.on('close', () => {
+      // Fires for BOTH stdin EOF and plugin disposal (reader.close() below);
+      // `disposed` guards teardown so HMR/dispose never exits the process.
+      stdinClosed = true
+      if (!disposed) disposePendingQuestions()
+      maybeExit()
+    })
+    output.write(`${welcome}\n> `)
+    return () => {
+      disposed = true
+      if (exitTimer !== undefined) clearTimeout(exitTimer)
+      disposePendingQuestions()
+      disposeUserInteractionProvider()
+      disposeStatusListener()
+      reader.close()
+    }
+  }, 'ui-stdio')
+}
+
+/**
+ * Open the terminal channel once its configured agent exists. Generated stdio
+ * projects boot the Cordis tree first and create or resume the agent from
+ * developer code immediately afterward, so stdin must remain untouched until
+ * the matching `agent/created` notification arrives.
+ * @param ctx - the context supplying the agent registry and event stream.
+ * @param config - presentation and target-agent configuration.
+ * @param runtime - process-I/O seam.
+ */
+export function mountStdio(ctx: Context, config: Config, runtime: StdioRuntime): void {
+  const agentId = AgentId(config.agent ?? 'main')
+  if (ctx.agents.get(agentId) !== undefined) {
+    createStdioChat(ctx, config, runtime)
+    return
+  }
+  const dispose = ctx.on('agent/created', (agent) => {
+    if (agent.id !== agentId) return
+    dispose()
+    createStdioChat(ctx, config, runtime)
+  })
+}
+
+/**
+ * Cordis entry point. Binds the real `process` streams and delegates to
+ * {@link mountStdio}; the indirection keeps the side-effecting handles out
+ * of the testable core, which is why the unit suite drives `createStdioChat`
+ * directly. This thin wrapper is exercised end-to-end by the keyless
+ * Loader-path e2e smoke in `examples/echo-agent` (the real product entry).
+ */
+/* v8 ignore start -- production stdio wiring; testable core is createStdioChat() (covered), exercised e2e by echo-agent keyless smoke */
+export function apply(ctx: Context, config: Config): void {
+  mountStdio(ctx, config, {
+    input: process.stdin,
+    output: process.stdout,
+    exit: code => process.exit(code),
+  })
+}
+/* v8 ignore stop */
--- a/packages/ui/stdio/tests/plugin-shape.spec.ts
+++ b/packages/ui/stdio/tests/plugin-shape.spec.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import Loader from '@cordisjs/plugin-loader'
+import * as stdio from '../src/index.ts'
+
+/** Real Loader export-path guard for the namespace stdio plugin. */
+describe('dsh-stdio plugin export shape', () => {
+  it('preserves name, inject, Config, and apply through Loader unwrapping', () => {
+    expect('default' in stdio).toBe(false)
+    expect(typeof stdio.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(stdio) as Record<string, unknown>
+    expect(unwrapped).toBe(stdio)
+    expect(unwrapped.name).toBe('ui-stdio')
+    expect(unwrapped.inject).toEqual(['agents', 'userInteraction'])
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})
--- a/packages/ui/stdio/tests/readline.spec.ts
+++ b/packages/ui/stdio/tests/readline.spec.ts
@@ -0,0 +1,54 @@
+import { EventEmitter } from 'node:events'
+import type { Readable, Writable } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import type { StdioRuntime } from '../src/index.ts'
+
+const createInterface = vi.hoisted(() => vi.fn(() => {
+  const reader = new EventEmitter() as EventEmitter & { close(): void }
+  reader.close = vi.fn()
+  return reader
+}))
+
+vi.mock('node:readline', () => ({ createInterface }))
+
+function fakeContext(): Context {
+  return {
+    on: vi.fn(() => vi.fn()),
+    effect: vi.fn((callback: () => () => void) => callback()),
+    // The UI seeds its label map from the registry at install; this suite only
+    // exercises readline terminal-mode selection, so an empty roster suffices.
+    agents: { list: vi.fn(() => []) },
+    userInteraction: { registerProvider: vi.fn(() => vi.fn()) },
+  } as unknown as Context
+}
+
+function fakeRuntime(inputIsTTY: boolean, outputIsTTY: boolean): StdioRuntime {
+  return {
+    input: { isTTY: inputIsTTY } as Readable & { isTTY: boolean },
+    output: { isTTY: outputIsTTY, write: vi.fn(() => true) } as unknown as Writable & { isTTY: boolean },
+    exit: vi.fn(),
+  }
+}
+
+describe('createStdioChat readline mode', () => {
+  it('enables terminal editing only when both stdio streams are TTYs', async () => {
+    const { createStdioChat } = await import('../src/index.ts')
+
+    const tty = fakeRuntime(true, true)
+    createStdioChat(fakeContext(), {}, tty)
+    expect(createInterface).toHaveBeenLastCalledWith({
+      input: tty.input,
+      output: tty.output,
+      terminal: true,
+    })
+
+    const piped = fakeRuntime(true, false)
+    createStdioChat(fakeContext(), {}, piped)
+    expect(createInterface).toHaveBeenLastCalledWith({
+      input: piped.input,
+      output: piped.output,
+      terminal: false,
+    })
+  })
+})
--- a/packages/ui/stdio/tests/stdio.spec.ts
+++ b/packages/ui/stdio/tests/stdio.spec.ts
@@ -0,0 +1,967 @@
+import { Readable, Writable } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { Session as RealSession, SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ModesService, { PLAN_MODE } from '@deepseek-ai/dsh-mode'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { createStdioChat, mountStdio, type Config, type StdioRuntime } from '../src/index.ts'
+
+/**
+ * Unit tests for the stdio UI plugin. They drive the REAL plugin body
+ * (`createStdioChat`) with an injected {@link StdioRuntime} so every render,
+ * input, EOF, and disposal branch runs without touching the real `process`
+ * streams — the I/O seam is what makes the per-file gate reachable. The
+ * `agents` service is real (`@deepseek-ai/dsh-agent`); a minimal fake `Agent`
+ * stands in for the loop, since the loop is the genuinely expensive collaborator
+ * and we only need its `status` + `send`/`steer` surface here.
+ */
+
+/** A controllable stdin: a Readable we push lines into and can end on demand. */
+function makeInput(): Readable & { feed(line: string): void; finish(): void } {
+  const stream = new Readable({ read() {} }) as Readable & { feed(line: string): void; finish(): void }
+  stream.feed = (line: string) => stream.push(`${line}\n`)
+  stream.finish = () => stream.push(null)
+  return stream
+}
+
+/** A stdout sink that accumulates everything written, for assertions. */
+function makeOutput(): { write: (s: string) => boolean; text: () => string } {
+  let buf = ''
+  return { write: (s: string) => { buf += s; return true }, text: () => buf }
+}
+
+function makeRuntime(over: Partial<StdioRuntime> = {}): {
+  runtime: StdioRuntime
+  input: ReturnType<typeof makeInput>
+  out: ReturnType<typeof makeOutput>
+  exit: ReturnType<typeof vi.fn>
+} {
+  const input = makeInput()
+  const out = makeOutput()
+  const exit = vi.fn()
+  return { runtime: { input, output: { write: out.write } as never, exit, ...over }, input, out, exit }
+}
+
+/** A minimal Agent fake exposing the surface the UI touches. */
+function makeAgent(id: string, status: AgentStatus = 'idle'): Agent & {
+  status: AgentStatus
+  sent: ContentBlock[][]
+  steered: ContentBlock[][]
+} {
+  const sent: ContentBlock[][] = []
+  const steered: ContentBlock[][] = []
+  return {
+    id: id as Agent['id'],
+    status,
+    sent,
+    steered,
+    // A minimal session stub: the UI reads only `session.header.id` (to map the
+    // session back to its agent id for the turn-boundary label).
+    session: { header: { id: `${id}-session` } },
+    send: (content: ContentBlock[]) => void sent.push(content),
+    steer: (content: ContentBlock[]) => void steered.push(content),
+  } as never
+}
+
+/** A session stub whose `header.id` matches an agent's, for `session/event` emits. */
+function makeSession(agentId: string): Session {
+  return { header: { id: `${agentId}-session` } } as Session
+}
+
+/** An `assistant/chunk` session event carrying one raw stream chunk. */
+function chunkEvent(chunk: StreamChunk): SessionEvent {
+  return { type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 0, chunk } }
+}
+
+const CONFIG: Config = { welcome: 'hi there', agent: 'main' }
+
+async function setup(config: Config = CONFIG, runtimeOver: Partial<StdioRuntime> = {}) {
+  const ctx = new Context()
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  const { runtime, input, out, exit } = makeRuntime(runtimeOver)
+  const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+    createStdioChat(inner, config, runtime)
+  }, { inject: ['agents', 'userInteraction'] }))
+  return { ctx, fiber, input, out, exit }
+}
+
+/** Drive a fake idle timer past the 200ms flush delay. */
+function flushExit(): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, 250))
+}
+
+describe('mountStdio readiness', () => {
+  it('leaves stdin untouched until the configured agent is created', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const { runtime, out } = makeRuntime()
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      mountStdio(inner, CONFIG, runtime)
+    }, { inject: ['agents', 'userInteraction'] }))
+
+    expect(out.text()).toBe('')
+    ctx.agents.register(makeAgent('other'))
+    expect(out.text()).toBe('')
+    ctx.agents.register(makeAgent('main'))
+    expect(out.text()).toBe('hi there\n> ')
+    await fiber.dispose()
+  })
+
+  it('opens immediately when the configured agent already exists', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    ctx.agents.register(makeAgent('main'))
+    const { runtime, out } = makeRuntime()
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      mountStdio(inner, CONFIG, runtime)
+    }, { inject: ['agents', 'userInteraction'] }))
+
+    expect(out.text()).toBe('hi there\n> ')
+    await fiber.dispose()
+  })
+
+  it('waits for main when no target agent is configured', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const { runtime, out } = makeRuntime()
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      mountStdio(inner, { welcome: 'ready' }, runtime)
+    }, { inject: ['agents', 'userInteraction'] }))
+
+    ctx.agents.register(makeAgent('other'))
+    expect(out.text()).toBe('')
+    ctx.agents.register(makeAgent('main'))
+    expect(out.text()).toBe('ready\n> ')
+    await fiber.dispose()
+  })
+})
+
+describe('createStdioChat rendering', () => {
+  it('writes the welcome banner and prompt on start', async () => {
+    const { out } = await setup()
+    expect(out.text()).toBe('hi there\n> ')
+  })
+
+  it('falls back to default welcome/agent when called with empty config', async () => {
+    // createStdioChat is exported and may be driven directly (bypassing the
+    // Loader's schemastery validation), so it must default welcome/agent itself.
+    const { out } = await setup({})
+    expect(out.text()).toBe('ready.\n> ')
+    // And it drives the default agent id 'main'.
+  })
+
+  it('detects readline terminal mode from both stream TTY flags', async () => {
+    for (const [inputTTY, outputTTY] of [[true, false], [true, true]] as const) {
+      const ctx = new Context()
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(UserInteractionService)
+      let text = ''
+      const output = new Writable({
+        write(chunk, _encoding, callback) {
+          text += String(chunk)
+          callback()
+        },
+      }) as Writable & { isTTY?: boolean }
+      const { runtime } = makeRuntime({ output })
+      ;(runtime.input as Readable & { isTTY?: boolean }).isTTY = inputTTY
+      output.isTTY = outputTTY
+      const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+        createStdioChat(inner, CONFIG, runtime)
+      }, { inject: ['agents', 'userInteraction'] }))
+
+      expect(text).toContain('hi there')
+      await fiber.dispose()
+    }
+  })
+
+  it('renders text-delta chunks verbatim', async () => {
+    const { ctx, out } = await setup()
+    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
+    expect(out.text()).toContain('hello')
+  })
+
+  it('wraps reasoning-delta in the dim SGR and resets on the following text-delta', async () => {
+    const { ctx, out } = await setup()
+    const session = makeSession('main')
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'think' }))
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'more' }))
+    ctx.emit('session/event', session, chunkEvent({ type: 'text-delta', index: 0, text: 'answer' }))
+    expect(out.text()).toContain('\x1B[2mthinkmore\x1B[0m\nanswer')
+  })
+
+  it('ignores stream-chunk types it does not render', async () => {
+    const { ctx, out } = await setup()
+    const before = out.text()
+    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'block-start', index: 0, blockType: 'text' }))
+    expect(out.text()).toBe(before)
+  })
+
+  it('renders turn/start and turn/end markers from the session feed', async () => {
+    const { ctx, out } = await setup()
+    const agent = makeAgent('main')
+    // agent/created populates the session-id → agent-id label map.
+    ctx.emit('agent/created', agent)
+    const session = makeSession('main')
+    ctx.emit('session/event', session, {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 3, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main turn 3] ')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 2, time: 0, data: { turn: 3, reason: { kind: 'completed' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('\n> ')
+  })
+
+  it('falls back to the session id as the label when no agent is mapped', async () => {
+    const { ctx, out } = await setup()
+    // No agent/created emitted, so the label map is empty — the header id shows.
+    ctx.emit('session/event', makeSession('orphan'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[orphan-session turn 1] ')
+  })
+
+  it('seeds labels for agents already registered before the UI installs', async () => {
+    // The pre-created `main` agent (and any agent surviving an HMR reload of just this fiber)
+    // fired its `agent/created` before the UI's listener existed, so the live listener alone
+    // would miss it. Seeding from `ctx.agents.list()` preserves the `[main turn N]` label instead
+    // of falling back to the raw session id.
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const agent = makeAgent('main')
+    ctx.agents.register(agent) // registered BEFORE the UI plugin below
+    const { runtime, out } = makeRuntime()
+    await ctx.plugin(Object.assign((inner: Context) => {
+      createStdioChat(inner, CONFIG, runtime)
+    }, { inject: ['agents', 'userInteraction'] }))
+    ctx.emit('session/event', makeSession('main'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main turn 5] ')
+  })
+
+  it('resets dim styling at turn/end if a turn ends mid-reasoning', async () => {
+    const { ctx, out } = await setup()
+    const session = makeSession('main')
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'mid' }))
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 1, time: 0, data: { turn: 1, reason: { kind: 'completed' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mmid\x1B[0m')
+  })
+
+  it('drops the label mapping on agent/disposed', async () => {
+    const { ctx, out } = await setup()
+    const agent = makeAgent('main')
+    ctx.emit('agent/created', agent)
+    ctx.emit('agent/disposed', agent)
+    // After disposal the map no longer resolves the agent id — fall back to the
+    // session header id.
+    ctx.emit('session/event', makeSession('main'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main-session turn 1] ')
+  })
+
+  it('renders tool/call and tool/result session events', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    const callEvent = {
+      type: 'tool/call', seq: 1, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{"command":"ls"}' },
+    } as SessionEvent
+    ctx.emit('session/event', session, callEvent)
+    expect(out.text()).toContain('[tool call] bash({"command":"ls"})')
+
+    const resultEvent = {
+      type: 'tool/result', seq: 2, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', content: [{ type: 'text', text: 'file.txt' }], isError: false },
+    } as SessionEvent
+    ctx.emit('session/event', session, resultEvent)
+    expect(out.text()).toContain('[tool result] file.txt')
+  })
+
+  it('renders a todo/write session event as a glyphed checklist', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    ctx.emit('session/event', session, {
+      type: 'todo/write', seq: 1, time: 0,
+      data: { todos: [
+        { content: 'read the code', status: 'completed' },
+        { content: 'write the fix', status: 'in_progress' },
+        { content: 'run the tests', status: 'pending' },
+      ] },
+    } as SessionEvent)
+    const text = out.text()
+    expect(text).toContain('[todos]')
+    expect(text).toContain('[x] read the code')
+    expect(text).toContain('[~] write the fix')
+    expect(text).toContain('[ ] run the tests')
+  })
+
+  it('resets dim styling when a todo/write interrupts reasoning', async () => {
+    const { ctx, out } = await setup()
+    ctx.emit('session/event', {} as Session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    ctx.emit('session/event', {} as Session, {
+      type: 'todo/write', seq: 1, time: 0,
+      data: { todos: [{ content: 'a task', status: 'pending' }] },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mr\x1B[0m')
+  })
+
+  it('resets dim styling when a tool/call interrupts reasoning', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    ctx.emit('session/event', session, {
+      type: 'tool/call', seq: 1, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{}' },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mr\x1B[0m')
+  })
+
+  it('ignores session events it does not render', async () => {
+    const { ctx, out } = await setup()
+    const before = out.text()
+    ctx.emit('session/event', {} as Session, {
+      type: 'user/message', seq: 1, time: 0,
+      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
+    } as SessionEvent)
+    expect(out.text()).toBe(before)
+  })
+})
+
+describe('createStdioChat input', () => {
+  it('answers a pending user question instead of sending the line to the agent', async () => {
+    const { ctx, input, out } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'confirm',
+        header: 'Confirm',
+        question: 'Proceed with the edit?',
+        options: [{ label: 'Yes', description: 'Apply the edit now.' }],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('Use a smaller change')
+
+    await expect(answer).resolves.toEqual({ answers: [{ id: 'confirm', selected: [], custom: 'Use a smaller change' }] })
+    expect(agent.sent).toEqual([])
+    expect(out.text()).toContain('[Confirm] Proceed with the edit?')
+    expect(out.text()).toContain('1. Yes')
+    expect(out.text()).toContain('Apply the edit now.')
+  })
+
+  it('answers a pending user question by numeric option selection', async () => {
+    const { ctx, input } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [
+          { label: 'Safe' },
+          { label: 'Fast' },
+        ],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Fast'] }],
+    })
+  })
+
+  it('renders options in input order and selects by displayed number', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'topic',
+        question: 'Which topic?',
+        options: [
+          { label: 'Hobbies' },
+          { label: 'Work', description: 'Questions about current projects.' },
+          { label: 'Casual', description: 'Easy conversation.' },
+        ],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+
+    expect(out.text()).toContain([
+      'Which topic?',
+      '  1. Hobbies',
+      '  2. Work',
+      '     Questions about current projects.',
+      '  3. Casual',
+      '     Easy conversation.',
+    ].join('\n'))
+    input.feed('3')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'topic', selected: ['Casual'] }],
+    })
+  })
+
+  it('answers a multi-select question with multiple numeric selections', async () => {
+    const { ctx, input } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'targets',
+        question: 'What should I update?',
+        options: [{ label: 'Tests' }, { label: 'Docs' }, { label: 'Code' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('1 1, 3')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'targets', selected: ['Tests', 'Code'] }],
+    })
+  })
+
+  it('accepts non-numeric multi-select input as a custom answer', async () => {
+    const { ctx, input } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'targets',
+        question: 'What should I update?',
+        options: [{ label: 'Tests' }, { label: 'Docs' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('the release notes')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'targets', selected: [], custom: 'the release notes' }],
+    })
+  })
+
+  it('asks every question in a batch and returns answers by id', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [
+        { id: 'language', question: 'Which language?', options: [{ label: 'Python' }, { label: 'TypeScript' }] },
+        { id: 'note', question: 'Any note?' },
+      ],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('\nAny note?\n')
+    input.feed('ship today')
+
+    await expect(answer).resolves.toEqual({
+      answers: [
+        { id: 'language', selected: ['TypeScript'] },
+        { id: 'note', selected: [], custom: 'ship today' },
+      ],
+    })
+  })
+
+  it('re-prompts when option input is invalid', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when single-select option input is out of range', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when multi-select input contains no option numbers', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed(',')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when an option question receives an empty answer', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when a question receives an empty answer', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'path', question: 'What should I use?' }] })
+    await new Promise(r => setImmediate(r))
+    input.feed('')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter an answer.')
+    input.feed('Use defaults')
+
+    await expect(answer).resolves.toEqual({ answers: [{ id: 'path', selected: [], custom: 'Use defaults' }] })
+  })
+
+  it('rejects an active question when its signal aborts', async () => {
+    const { ctx } = await setup()
+    const controller = new AbortController()
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'continue', question: 'Continue?' }], signal: controller.signal })
+    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await new Promise(r => setImmediate(r))
+
+    controller.abort()
+
+    await rejected
+  })
+
+  it('continues to the next queued question when the active question aborts', async () => {
+    const { ctx, input, out } = await setup()
+    const controller = new AbortController()
+    const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }], signal: controller.signal })
+    const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }] })
+    await new Promise(r => setImmediate(r))
+
+    controller.abort()
+    await firstRejected
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('\nSecond?\n')
+    input.feed('second answer')
+
+    await expect(second).resolves.toEqual({ answers: [{ id: 'second', selected: [], custom: 'second answer' }] })
+  })
+
+  it('skips a queued question whose signal aborted before it became active', async () => {
+    const { ctx, input, out } = await setup()
+    const controller = new AbortController()
+    const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] })
+    const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal })
+    await new Promise(r => setImmediate(r))
+
+    controller.abort()
+
+    await expect(Promise.race([
+      second.then(
+        () => 'resolved',
+        (error: unknown) => (error as { code?: string }).code,
+      ),
+      new Promise<string>((resolve) => { setImmediate(() => { resolve('pending') }) }),
+    ])).resolves.toBe('ASK_ABORTED')
+    expect(out.text()).not.toContain('\nSecond?\n')
+    input.feed('first answer')
+    await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] })
+  })
+
+  it('removes an aborted queued question without promoting later queued work early', async () => {
+    const { ctx, input, out } = await setup()
+    const controller = new AbortController()
+    const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] })
+    const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal })
+    const third = ctx.userInteraction.ask({ questions: [{ id: 'third', question: 'Third?' }] })
+    await new Promise(r => setImmediate(r))
+
+    controller.abort()
+
+    await expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    expect(out.text()).toContain('\nFirst?\n')
+    expect(out.text()).not.toContain('\nSecond?\n')
+    expect(out.text()).not.toContain('\nThird?\n')
+    input.feed('first answer')
+    await new Promise(r => setImmediate(r))
+
+    expect(out.text()).toContain('\nThird?\n')
+    input.feed('third answer')
+
+    await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] })
+    await expect(third).resolves.toEqual({ answers: [{ id: 'third', selected: [], custom: 'third answer' }] })
+  })
+
+  it('rejects active and queued questions when the UI is disposed', async () => {
+    const { ctx, fiber } = await setup()
+    const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
+    const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
+    const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await new Promise(r => setImmediate(r))
+
+    await fiber.dispose()
+
+    await activeRejected
+    await queuedRejected
+  })
+
+  it('rejects active and queued questions when stdin closes before the user answers', async () => {
+    const { ctx, input, exit } = await setup()
+    const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
+    const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
+    const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await new Promise(r => setImmediate(r))
+
+    input.finish()
+    await new Promise(r => setImmediate(r))
+
+    await activeRejected
+    await queuedRejected
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('rejects new questions immediately after stdin has closed', async () => {
+    const { ctx, input, out } = await setup()
+    input.finish()
+    await new Promise(r => setImmediate(r))
+    const before = out.text()
+
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Too late?' }] })
+
+    await expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    expect(out.text()).toBe(before)
+  })
+
+  it('sends a typed line to an idle agent', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('do a thing')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([[{ type: 'text', text: 'do a thing' }]])
+    expect(agent.steered).toEqual([])
+  })
+
+  it('steers a typed line into a running agent', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main', 'running')
+    ctx.agents.register(agent)
+    input.feed('steer me')
+    await new Promise(r => setImmediate(r))
+    expect(agent.steered).toEqual([[{ type: 'text', text: 'steer me' }]])
+    expect(agent.sent).toEqual([])
+  })
+
+  it('ignores blank lines', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main')
+    ctx.agents.register(agent)
+    input.feed('   ')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([])
+  })
+
+  it('logs and drops a line when the target agent is not running', async () => {
+    const { ctx, input } = await setup()
+    const spy = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {})
+    input.feed('nobody home')
+    await new Promise(r => setImmediate(r))
+    expect(spy).toHaveBeenCalledWith('ui-stdio: agent "%s" is not running', 'main')
+  })
+
+  it('drives the agent named in config, not a hardcoded id', async () => {
+    const { ctx, input } = await setup({ welcome: 'w', agent: 'worker' })
+    const agent = makeAgent('worker')
+    ctx.agents.register(agent)
+    input.feed('hi')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toHaveLength(1)
+  })
+})
+
+describe('createStdioChat EOF exit', () => {
+  it('exits immediately on EOF when no work was submitted', async () => {
+    const { input, exit } = await setup()
+    input.finish()
+    await flushExit()
+    expect(exit).toHaveBeenCalledWith(0)
+  })
+
+  it('waits for the agent to settle idle after running before exiting', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    input.finish()
+    await new Promise(r => setImmediate(r))
+    // Work submitted but no 'running' observed yet — must NOT exit.
+    expect(exit).not.toHaveBeenCalled()
+    // The turn starts, then settles.
+    ctx.emit('agent/status', agent, 'running')
+    ;(agent as { status: AgentStatus }).status = 'idle'
+    ctx.emit('agent/status', agent, 'idle')
+    await flushExit()
+    expect(exit).toHaveBeenCalledWith(0)
+  })
+
+  it('schedules the exit only once when idle fires repeatedly', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'running')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    ctx.emit('agent/status', agent, 'running') // sawRunning = true
+    input.finish()
+    await new Promise(r => setImmediate(r)) // let readline 'close' set stdinClosed
+    ;(agent as { status: AgentStatus }).status = 'idle'
+    // Two idle signals while stdin is already closed: the first arms the timer,
+    // the second must hit the already-scheduled guard, not arm a second.
+    ctx.emit('agent/status', agent, 'idle')
+    ctx.emit('agent/status', agent, 'idle')
+    await flushExit()
+    expect(exit).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not exit on an idle transition for a different agent', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    input.finish()
+    const other = makeAgent('other')
+    ctx.emit('agent/status', other, 'running')
+    ctx.emit('agent/status', other, 'idle')
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('does not exit while a turn is still running at EOF', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    ctx.emit('agent/status', agent, 'running')
+    ;(agent as { status: AgentStatus }).status = 'running'
+    input.finish()
+    // sawRunning is true, but the agent is still running — the idle gate holds.
+    ctx.emit('agent/status', agent, 'idle') // a stale/duplicate signal while status stays 'running'
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+})
+
+describe('createStdioChat disposal (HMR safety)', () => {
+  it('never exits the process when EOF arrives after fiber dispose', async () => {
+    const { fiber, input, exit } = await setup()
+    await fiber.dispose()
+    // A late EOF after disposal (reader.close() also fires 'close') must not exit.
+    input.finish()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('cancels a scheduled exit if disposed within the flush window', async () => {
+    const { fiber, input, exit } = await setup()
+    // EOF with no work submitted schedules the 200ms flush-then-exit timer.
+    input.finish()
+    await new Promise(r => setImmediate(r))
+    expect(exit).not.toHaveBeenCalled() // not yet — still inside the window
+    // Dispose BEFORE the timer fires: the tracked handle must be cleared.
+    await fiber.dispose()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('stops handling input after dispose', async () => {
+    const { ctx, fiber, input } = await setup()
+    const agent = makeAgent('main')
+    ctx.agents.register(agent)
+    await fiber.dispose()
+    // The readline interface is closed on dispose; a late line reaches no handler.
+    input.feed('too late')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([])
+  })
+
+  it('removes the agent/status listener on dispose', async () => {
+    const { ctx, fiber, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    await fiber.dispose()
+    // After dispose, status transitions must neither throw nor schedule an exit
+    // (the listener and the EOF-exit path are both torn down).
+    expect(() => {
+      ctx.emit('agent/status', agent, 'running')
+      ctx.emit('agent/status', agent, 'idle')
+    }).not.toThrow()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+})
+
+describe('createStdioChat /mode command', () => {
+  /** An agent fake carrying a REAL session, so `ctx.modes` folds a genuine log. */
+  function makeModeAgent(id: string): Agent & { sent: ContentBlock[][] } {
+    const sent: ContentBlock[][] = []
+    return {
+      id: id as Agent['id'],
+      status: 'idle',
+      options: {},
+      sent,
+      session: new RealSession(SessionId(`${id}-session`)),
+      send: (content: ContentBlock[]) => void sent.push(content),
+      steer: () => {},
+    } as never
+  }
+
+  async function setupWithModes() {
+    const bundle = await setup()
+    await bundle.ctx.plugin(SystemPrompt)
+    await bundle.ctx.plugin(ToolRegistry)
+    await bundle.ctx.plugin(ModesService)
+    const agent = makeModeAgent('main')
+    bundle.ctx.agents.register(agent)
+    return { ...bundle, agent }
+  }
+
+  it('reports when session modes are not composed', async () => {
+    const { ctx, input, out } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('/mode')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('session modes are not composed in this deployment')
+    expect(agent.sent).toEqual([])
+  })
+
+  it('prints the current and available modes, never sending the line to the model', async () => {
+    const { input, out, agent } = await setupWithModes()
+    input.feed('/mode')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('mode: default — available: default, plan')
+    expect(agent.sent).toEqual([])
+  })
+
+  it('switches the mode as a pending intent and echoes the banner', async () => {
+    const { ctx, input, out, agent } = await setupWithModes()
+    input.feed('/mode plan')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('mode → plan (applies from the next turn)')
+    expect(ctx.modes.get(agent)).toEqual({ current: 'default', pending: PLAN_MODE })
+    input.feed('/mode')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('mode: default (pending: plan) — available: default, plan')
+    expect(agent.sent).toEqual([])
+  })
+
+  it('prints the validation error for an unknown mode name', async () => {
+    const { ctx, input, out, agent } = await setupWithModes()
+    input.feed('/mode nope')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('unknown mode "nope" — available modes: default, plan')
+    expect(ctx.modes.get(agent)).toEqual({ current: 'default' })
+  })
+})
+
+describe('createStdioChat /mode during an active question', () => {
+  it('reserves /mode while a question is pending — the command is never recorded as the answer', async () => {
+    const bundle = await setup()
+    await bundle.ctx.plugin(SystemPrompt)
+    await bundle.ctx.plugin(ToolRegistry)
+    await bundle.ctx.plugin(ModesService)
+    const agent = {
+      id: 'main' as Agent['id'],
+      status: 'idle',
+      options: {},
+      session: new RealSession(SessionId('main-session')),
+      send: () => {},
+      steer: () => {},
+    } as never as Agent
+    bundle.ctx.agents.register(agent)
+
+    const answer = bundle.ctx.userInteraction.ask({
+      questions: [{
+        id: 'plan-review',
+        header: 'Plan review',
+        question: 'Approve this plan and leave plan mode?',
+        options: [{ label: 'Approve' }, { label: 'Keep planning' }],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+
+    // The command runs as a command: the mode switches, the question stays
+    // pending (it still owns the next non-command line).
+    bundle.input.feed('/mode plan')
+    await new Promise(r => setImmediate(r))
+    expect(bundle.out.text()).toContain('mode → plan (applies from the next turn)')
+    expect(bundle.ctx.modes.get(agent)).toEqual({ current: 'default', pending: PLAN_MODE })
+
+    bundle.input.feed('1')
+    await expect(answer).resolves.toEqual({ answers: [{ id: 'plan-review', selected: ['Approve'] }] })
+  })
+
+  it('logs and drops /mode when the target agent is not running', async () => {
+    const { ctx, input } = await setup()
+    const spy = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {})
+    input.feed('/mode plan')
+    await new Promise(r => setImmediate(r))
+    expect(spy).toHaveBeenCalledWith('ui-stdio: agent "%s" is not running', 'main')
+  })
+})
--- a/packages/ui/stdio/tsconfig.json
+++ b/packages/ui/stdio/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../mode/mode"
+    },
+    {
+      "path": "../user-interaction"
+    }
+  ]
+}