feat(ui): add dedicated TUI package

Move the interactive pi-tui front door into @deepseek-ai/dsh-tui while keeping @deepseek-ai/dsh-stdio line-oriented for pipes. Select the terminal package in the demo app, preserve logger ownership, and cover the production Loader composition with a PTY smoke test.
2026-07-17 12:01:37 +08:00
parent 4139e093dd
commit 1119c537d0
49 changed files with 2808 additions and 93 deletions
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -5,11 +5,11 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + `tool-skill` + `agent-loop`) |
-| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal stdio chat app: the spine + console logger + readline UI + a pre-created `main` agent, with a boot `bin` |
+| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal chat app: the spine + JSONL persistence + TTY-selected `dsh-tui`/`dsh-stdio` front door + a pre-created `main` agent, with a boot `bin` |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |

-`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with opposite front-door clusters (console logger + readline UI vs the stdout-owning ACP bridge) and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with terminal and ACP front-door clusters and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.

 These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.

--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -33,7 +33,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
+- **presentation + per-app infra** — the terminal (`dsh-tui` / `dsh-stdio`) or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.

 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.

--- a/packages/examples/stdio-demo/README.md
+++ b/packages/examples/stdio-demo/README.md
@@ -1,8 +1,8 @@
 # @deepseek-ai/dsh-stdio-demo

-The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with JSONL persistence, human interaction, a pre-created `main` agent, and a TTY-selected pi-tui/readline terminal front door. Its `bin` boots a leaf `cordis.yml`.

-It is the readline counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
+It is the terminal counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, while ACP reserves stdout for JSON-RPC and creates sessions from the client.

 ## What it bakes in

@@ -10,14 +10,15 @@ A terminal chat always wants the same cluster, so the package owns it rather tha

 | Plugin | Why it is here |
 |---|---|
-| `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
 | `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
-| `@deepseek-ai/dsh-stdio` | the readline UI, bound to the `main` agent |
+| `@cordisjs/plugin-logger-console` | readline diagnostics for non-TTY operation; omitted from the fullscreen TUI path |
+| `@deepseek-ai/dsh-stdio` | the line-oriented terminal channel, bound to `main` for pipes and automation |
+| `@deepseek-ai/dsh-tui` | the interactive pi-tui channel, bound to `main` for TTY pairs |

-`@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.
+`@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, not baked in here: it is a Loader-only, subprocess-only dev plugin whose constructor needs `node --expose-internals` plus a live `loader`. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.

 The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends.

@@ -33,7 +34,8 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
 | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
-| `welcome` | `ready.` | the stdin-chat banner |
+| `welcome` | `ready.` | terminal banner / TUI subtitle |
+| `ui` | owner defaults | app mode selection and nested `dsh-tui` presentation config |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |

 Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-demo` was started. Resumed sessions keep the cwd stored in the persisted session header.
@@ -45,7 +47,7 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
 ## Example leaf `cordis.yml`

 ```yaml
-# A REPL agent demo: hmr + the DeepSeek adapter + local bash, then this app.
+# A coding-agent demo: hmr + the DeepSeek adapter + local bash, then this app.
 - id: hmr
  name: '@cordisjs/plugin-hmr'
  config:
@@ -64,6 +66,8 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
  config:
    model: deepseek-v4-flash
    persona: 'You are a coding assistant powered by the {{model}} model.'
+    ui:
+      mode: auto
 ```

 Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo — "swap the backend, keep the app".
@@ -72,9 +76,9 @@ Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo —

 ### Composed terminal agent request

-**What the model sees**: Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.
+**What the model sees**: Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each terminal submission becomes a user message; submissions made while the agent runs steer the active turn.

-**Token effect**: Child prompt and schema costs repeat per request; user input and tool history grow until compaction. The welcome banner, logger output, and rendered transcript are terminal-only and add zero model tokens.
+**Token effect**: Child prompt and schema costs repeat per request; user input and tool history grow until compaction. The TUI/readline banners and rendered transcripts are terminal-only and add zero model tokens.

 ### Human-answer result

@@ -84,6 +88,6 @@ Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo —

 ## Known Limitations and Deferred Work

- **One pre-created `main` agent drives the readline UI** — there is no multi-session or concurrent-agent surface in this app; a run is one conversation.
+- **One pre-created `main` agent drives the terminal UI** — there is no multi-session or concurrent-agent surface in this app; a run is one conversation.
 - **The front-door cluster is fixed in code** — the JSONL persistence backend and the ask-user tooling are baked; a different composition is a leaf-level sibling entry or another app package.
 - **The question tool is not an approval answerer** — this app mounts `user-interaction` and `ask_user_question`, but not `ctx.approval`; a `tools/pre-execute` `ask` therefore fails closed unless the leaf composes an approval service and terminal answerer.
--- a/packages/examples/stdio-demo/package.json
+++ b/packages/examples/stdio-demo/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-stdio-demo",
-  "description": "Terminal stdio chat app: the agent-spine-demo bundle + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
+  "description": "Terminal chat app: agent spine + JSONL persistence + TTY pi-tui/readline front-door selection + pre-created main agent",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -32,14 +32,15 @@
  "peerDependencies": {
    "@cordisjs/plugin-include": "^1.0.4",
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-app-boot": "^0.0.1",
    "@cordisjs/plugin-logger-console": "^1.0.0",
+    "@deepseek-ai/dsh-app-boot": "^0.0.1",
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-stdio": "^0.0.1",
+    "@deepseek-ai/dsh-tui": "^0.0.1",
    "@deepseek-ai/dsh-tool-ask-user": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -49,8 +50,8 @@
  "devDependencies": {
    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@cordisjs/plugin-logger-console": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
@@ -58,6 +59,7 @@
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-stdio": "workspace:^",
+    "@deepseek-ai/dsh-tui": "workspace:^",
    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "@deepseek-ai/dsh-user-interaction": "workspace:^",
--- a/packages/examples/stdio-demo/src/bin.ts
+++ b/packages/examples/stdio-demo/src/bin.ts
@@ -2,7 +2,7 @@
 /**
 * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-demo [config]`, defaulting to the
 * cwd file. Shared `.env` loading, fail-loud Loader guards, and settled-tree boot live in
- * dsh-app-boot. The echo and REPL demos invoke this bin with their own leaf configs.
+ * dsh-app-boot. The echo and coding-agent demos invoke this bin with their own leaf configs.
 * @module @deepseek-ai/dsh-stdio-demo/bin
 */

--- a/packages/examples/stdio-demo/src/index.ts
+++ b/packages/examples/stdio-demo/src/index.ts
@@ -1,8 +1,9 @@
 /**
 * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}) plus the
- * coupled front-door cluster a terminal chat needs — a console logger, the independently
- * packaged readline UI, JSONL session persistence, the user-interaction seam with its
- * `ask_user_question` tool, and a pre-created `main` agent the UI drives.
+ * coupled front-door cluster a terminal chat needs — the independently packaged
+ * pi-tui and readline front doors, JSONL session persistence, the user-interaction
+ * seam with its `ask_user_question` tool, and a pre-created `main` agent the UI
+ * drives. Interactive terminals use `dsh-tui`; pipes use `dsh-stdio` plus logging.
 * Swappable adapters, executors, optional tools, and HMR stay in the leaf. This
 * Loader plugin intentionally exposes named exports only; a default export
 * would hide its `Config` schema (see docs/postmortem/0001).
@@ -20,9 +21,45 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiStdio from '@deepseek-ai/dsh-stdio'
+import * as uiTui from '@deepseek-ai/dsh-tui'

 export const name = 'stdio-demo'

+/** Terminal front door selected by the app bundle. */
+export type TerminalMode = 'auto' | 'readline' | 'tui'
+
+/** App-level terminal selection with nested TUI presentation settings. */
+export interface UiConfig {
+  /** Select a concrete front door or infer it from the process streams. */
+  mode?: TerminalMode
+  /** Settings forwarded only when the pi-tui front door is selected. */
+  tui?: uiTui.TuiConfig
+}
+
+const terminalModeSchema = z.union(['auto', 'readline', 'tui'] as const).default('auto')
+
+/** Schemastery schema for the app-level terminal selection. */
+export const UiConfigSchema: z<UiConfig> = z.object({
+  mode: terminalModeSchema,
+  tui: uiTui.TuiConfigSchema,
+})
+
+/**
+ * Resolve the app's terminal front door.
+ *
+ * @param config - App-level terminal selection.
+ * @param isTTY - Whether both process streams are interactive TTYs.
+ * @returns The concrete UI package to mount.
+ */
+export function resolveTerminalMode(config: UiConfig | undefined, isTTY: boolean): Exclude<TerminalMode, 'auto'> {
+  const mode = config?.mode ?? 'auto'
+  if (mode === 'auto') return isTTY ? 'tui' : 'readline'
+  if (mode === 'tui' && !isTTY) {
+    throw new Error('stdio-demo: TUI mode requires both stdin and stdout to be TTYs; use mode "readline" for pipes')
+  }
+  return mode
+}
+
 /**
 * App config: the swappable per-demo values, each routed to where the app wires
 * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
@@ -31,7 +68,7 @@ export const name = 'stdio-demo'
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
 * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory;
- * `welcome` is the UI banner.
+ * `welcome` is the UI banner and `ui` configures terminal mode/presentation.
 */
 export interface Config {
  /** Model name for the `main` agent (must have a registered adapter). */
@@ -44,8 +81,10 @@ export interface Config {
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
-  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
+  /** Terminal banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
+  /** Terminal front-door selection and pi-tui presentation settings. */
+  ui?: UiConfig
  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /** Model-facing bash tool config forwarded through agent-core. */
@@ -72,6 +111,7 @@ export const Config: z<Config> = z.object({
  // apply() fallbacks through named constants while retaining both boundaries.
  persistenceRoot: z.string().default('./.sessions'),
  welcome: z.string().default('ready.'),
+  ui: UiConfigSchema,
  skills: agentCore.SkillConfigSchema,
  toolBash: agentCore.ToolBashConfigSchema,
  toolTasks: agentCore.ToolTasksConfigSchema,
@@ -79,14 +119,18 @@ export const Config: z<Config> = z.object({
 })

 /**
- * Compose the spine with the stdio front door. The console logger comes first
- * (infra), then the agent-spine-demo bundle pre-creating the `main` agent from this
- * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
- * backend, then the readline UI bound to `main`. The `hmr` dev-reload plugin is
- * a leaf concern (see the module doc), so it is not mounted here.
+ * Compose the spine with one terminal front door. Interactive TTY pairs mount
+ * `dsh-tui` without a console exporter; pipes mount the readline `dsh-stdio`
+ * channel with the console logger. The `hmr` dev-reload plugin remains a leaf
+ * concern.
+ *
+ * @param ctx - Context receiving the app's child plugins.
+ * @param config - App configuration routed to the spine and front door.
+ * @param isTTY - Whether both terminal streams are interactive TTYs.
 */
-export function apply(ctx: Context, config: Config): void {
-  ctx.plugin(ConsoleExporter)
+export function composeTerminalApp(ctx: Context, config: Config, isTTY: boolean): void {
+  const mode = resolveTerminalMode(config.ui, isTTY)
+  if (mode === 'readline') ctx.plugin(ConsoleExporter)
  ctx.plugin(agentCore, {
    ...config.persona !== undefined ? { persona: config.persona } : {},
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
@@ -104,5 +148,21 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
  ctx.plugin(UserInteractionService)
  ctx.plugin(toolAskUser)
-  ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' })
+  if (mode === 'tui') {
+    ctx.plugin(uiTui, {
+      ...config.ui?.tui,
+      welcome: config.welcome ?? 'ready.',
+      agent: 'main',
+    })
+  } else {
+    ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' })
+  }
 }
+
+/** Compose the configured terminal front door with the agent app. */
+/* v8 ignore start -- production stream capability wiring; composeTerminalApp is unit-covered,
+   and the coding-agent PTY smoke covers the interactive process path */
+export function apply(ctx: Context, config: Config): void {
+  composeTerminalApp(ctx, config, process.stdin.isTTY && process.stdout.isTTY)
+}
+/* v8 ignore stop */
--- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
+++ b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
@@ -10,8 +10,8 @@ import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'

 /**
- * Unit coverage for app composition and config forwarding: console logger, pre-created main agent,
- * agent-core spine, JSONL backend, and readline UI. HMR is a Loader-only leaf concern covered by the
+ * Unit coverage for app composition and config forwarding: pre-created main agent, agent-core spine,
+ * JSONL backend, and adaptive terminal UI. HMR is a Loader-only leaf concern covered by the
 * keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise
 * survive namespace collapse while silently losing its schema.
 */
@@ -65,6 +65,47 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 }

 describe('dsh-stdio-demo app', () => {
+  it('selects readline for pipes and dsh-tui for interactive terminal pairs', () => {
+    expect(stdioAgent.resolveTerminalMode(undefined, false)).toBe('readline')
+    expect(stdioAgent.resolveTerminalMode(undefined, true)).toBe('tui')
+    expect(stdioAgent.resolveTerminalMode({ mode: 'readline' }, true)).toBe('readline')
+    expect(stdioAgent.resolveTerminalMode({ mode: 'tui' }, true)).toBe('tui')
+    expect(() => stdioAgent.resolveTerminalMode({ mode: 'tui' }, false)).toThrow('requires both stdin and stdout')
+  })
+
+  it('composes only the selected terminal package and keeps TUI settings in dsh-tui', () => {
+    const calls: Array<{ name: string; config: unknown }> = []
+    const ctx = {
+      plugin(plugin: { name?: string }, config?: unknown) {
+        calls.push({ name: plugin.name ?? '', config })
+      },
+    } as unknown as Context
+
+    stdioAgent.composeTerminalApp(ctx, {
+      model: 'mock',
+      welcome: 'TUI ready',
+      ui: { mode: 'tui', tui: { color: false, maxToolOutputLines: 3 } },
+    }, true)
+    expect(calls.map(call => call.name)).toContain('ui-tui')
+    expect(calls.map(call => call.name)).not.toContain('ui-stdio')
+    expect(calls.map(call => call.name)).not.toContain('ConsoleExporter')
+    expect(calls.find(call => call.name === 'ui-tui')?.config).toMatchObject({
+      agent: 'main', welcome: 'TUI ready', color: false, maxToolOutputLines: 3,
+    })
+
+    calls.length = 0
+    stdioAgent.composeTerminalApp(ctx, { model: 'mock', ui: { mode: 'tui' } }, true)
+    expect(calls.find(call => call.name === 'ui-tui')?.config).toMatchObject({
+      agent: 'main', welcome: 'ready.',
+    })
+
+    calls.length = 0
+    stdioAgent.composeTerminalApp(ctx, { model: 'mock', ui: { mode: 'readline' } }, false)
+    expect(calls.map(call => call.name)).toContain('ui-stdio')
+    expect(calls.map(call => call.name)).toContain('ConsoleExporter')
+    expect(calls.map(call => call.name)).not.toContain('ui-tui')
+  })
+
  it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig() })
    // The spine services (brought up by the agent-core bundle) are all present.
--- a/packages/examples/stdio-demo/tsconfig.json
+++ b/packages/examples/stdio-demo/tsconfig.json
@@ -38,6 +38,9 @@
    {
      "path": "../../ui/stdio"
    },
+    {
+      "path": "../../ui/tui"
+    },
    {
      "path": "../../ui/tool-ask-user"
    },
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -6,4 +6,4 @@ The model-facing todo tool. A single **product** package — there is no interfa
 |---|---|---|
 | `tool-todo/` | Model-facing `todo_write` tool; writes the whole list to the session log (`todo/write`) | (registers on `ctx.tools`) |

-The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [stdio app's readline UI](../examples/stdio-demo) prints the list, the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate.
+The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [terminal app](../examples/stdio-demo) shows a persistent TUI plan or readline checklist, while the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate.
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -18,7 +18,7 @@ Beyond the schema's type/required/enum checks, `execute` rejects an empty or dup

 ## Rendering

-The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [stdio app's readline UI](../../examples/stdio-demo) prints a glyphed checklist, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).
+The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [terminal app](../../examples/stdio-demo) shows a persistent TUI plan or readline checklist, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).

 ## Export shape

--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -9,12 +9,13 @@ Integrations that expose the agent to an external editor or client. These are **
 | `permission/` | User-facing permission presets (`workspace-write`/`danger-full-access`): one product-level select bundling the sandbox-mode and approval-policy knobs, written through to their session events | `ctx.permission` |
 | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` |
 | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) |
-| `stdio/` | Terminal readline channel over `ctx.agents`, `session/event`, and `ctx.userInteraction`; agent lifecycle stays with app/developer code | (drives `ctx.agents`) |
+| `stdio/` | Line-oriented terminal channel for pipes and automation; drives `ctx.agents`, renders `session/event`, and answers `ctx.userInteraction` | (drives `ctx.agents`) |
+| `tui/` | Interactive pi-tui terminal channel for TTY sessions; renders `session/event`, tool presentation intents, and answers `ctx.userInteraction` | (drives `ctx.agents`) |
 | `jsonrpc/` | Stdio JSON-RPC server for out-of-process SDK clients | (drives `ctx.agents`) |
 | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |

-A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). The [`stdio`](stdio/README.md) plugin is the unstructured readline analogue of the `acp` bridge; app bundles and SDK projects compose it explicitly with the services and tools their product profile selects.
+A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). The [`stdio`](stdio/README.md) and [`tui`](tui/README.md) plugins are the two terminal front doors: one is line-oriented for pipes, the other is interactive for TTYs. App bundles and SDK projects compose the appropriate channel explicitly with the services and tools their product profile selects.

 `user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers.

-The runnable app bundles that bake these bridges into boot bins — the stdio chat app, the ACP server app, and the JSON-RPC SDK-runtime bin — live in [`examples/`](../examples/README.md) (`stdio-demo`, `acp-demo`, `jsonrpc-demo`), each composed over the [`agent-spine-demo`](../examples/agent-spine-demo/README.md) bundle. `ui/` keeps the reusable bridge/channel plugins and the `app-boot` glue; each front door owns its stdout policy, and a leaf `cordis.yml` supplies backends and optional tools.
+The runnable app bundles that bake these bridges into boot bins — the terminal chat app, the ACP server app, and the JSON-RPC SDK-runtime bin — live in [`examples/`](../examples/README.md) (`stdio-demo`, `acp-demo`, `jsonrpc-demo`), each composed over the [`agent-spine-demo`](../examples/agent-spine-demo/README.md) bundle. `ui/` keeps the reusable bridge/channel plugins and the `app-boot` glue; each front door owns its stdout policy, and a leaf `cordis.yml` supplies backends and optional tools.
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -2,7 +2,7 @@

 Agent Client Protocol bridge over JSON-RPC stdio. Editors can create or resume agents, stream their events, answer questions and approvals, and render tool calls. One connection supports multiple isolated sessions; Zed is the primary compatibility target.

-It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.
+It is a **client-driver / UI plugin**, the structured analogue of the terminal `dsh-tui`/`dsh-stdio` channels — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.

 ## Service / plugin

--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -0,0 +1,56 @@
+# @deepseek-ai/dsh-tui
+
+The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should compose [`@deepseek-ai/dsh-stdio`](../stdio/README.md) instead.
+
+This package owns interactive terminal presentation and input only. It injects `agents`, `tools`, and `userInteraction`, then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
+
+The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions as keyboard-driven overlays. Surface replacement events rebuild the transcript so compacted history does not reappear.
+
+While the agent is running, editor submissions call `agent.steer()`; otherwise they call `agent.send()`. Ctrl+C or Escape cancels a running turn. Ctrl+O expands tool cards, Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle. `/help`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` provide the same actions without key chords.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `welcome` | `ready.` | Header subtitle |
+| `agent` | `main` | Agent id driven by the terminal |
+| `showReasoning` | `true` | Render reasoning blocks |
+| `maxToolOutputLines` | `12` | Collapsed tool-card output limit |
+| `maxQuestionOptions` | `8` | Visible options in a question overlay |
+| `questionDialogWidth` | `72` | Question-overlay width in columns |
+| `questionDialogMaxHeight` | `20` | Question-overlay maximum rows |
+| `showHardwareCursor` | `false` | Show the hardware cursor at pi-tui's IME marker |
+| `color` | `true` | Apply the built-in ANSI palette |
+| `title` | `DeepSeek Harness` | Terminal window title |
+
+```yaml
+- id: terminal
+  name: '@deepseek-ai/dsh-tui'
+  config:
+    welcome: 'Coding agent ready.'
+    agent: main
+    showReasoning: true
+    maxToolOutputLines: 12
+```
+
+Startup fails before mounting when either process stream is not a TTY. Disposal stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR.
+
+## Model Experience
+
+### Interactive prompt input
+
+**What the model sees**: Each non-empty editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. Slash commands and keybindings are TUI-only.
+
+**Token effect**: Submitted text is retained under the agent loop's normal session-history and compaction rules. Headers, cards, Markdown rendering, status lines, plans, and help text add no tokens.
+
+### Interactive user-question answers
+
+**What the model sees**: When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels or `custom` text. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`.
+
+**Token effect**: Waiting and terminal overlays 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 owns the transcript and editor** — questions from other agents can still use the shared overlay provider, but session rendering and prompt input remain bound to `agent`.
+- **Tool cards are text terminal presentations** — terminal, diff, and generic cards use tool-owned titles/content, but session content currently has no image block for inline image rendering.
+- **Non-TTY operation is intentionally unsupported** — app bundles that need automation must select `dsh-stdio` before mounting this plugin rather than expecting an internal fallback.
--- a/packages/ui/tui/package.json
+++ b/packages/ui/tui/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@deepseek-ai/dsh-tui",
+  "description": "Interactive pi-tui terminal front door for DeepSeek Harness agents",
+  "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-session": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "0.80.7",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
--- a/packages/ui/tui/tests/plugin-shape.spec.ts
+++ b/packages/ui/tui/tests/plugin-shape.spec.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import Loader from '@cordisjs/plugin-loader'
+import * as tui from '../src/index.ts'
+
+/** Real Loader export-path guard for the namespace TUI plugin. */
+describe('dsh-tui plugin export shape', () => {
+  it('preserves name, inject, Config, and apply through Loader unwrapping', () => {
+    expect('default' in tui).toBe(false)
+    expect(typeof tui.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(tui) as Record<string, unknown>
+    expect(unwrapped).toBe(tui)
+    expect(unwrapped.name).toBe('ui-tui')
+    expect(unwrapped.inject).toEqual(['agents', 'userInteraction', 'tools'])
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -0,0 +1,952 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Terminal } from '@earendil-works/pi-tui'
+import AgentRegistry, { AgentId, type Agent, type AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import {
+  createTuiChat,
+  mountTui,
+  resolveTuiConfig,
+  type Config,
+  type TuiRuntime,
+} from '../src/index.ts'
+
+class FakeTerminal implements Terminal {
+  columns = 88
+  rows = 32
+  kittyProtocolActive = false
+  output = ''
+  title = ''
+  progress: boolean[] = []
+  started = 0
+  stopped = 0
+  drainInput = vi.fn(() => Promise.resolve())
+  private onInput: (data: string) => void = () => {}
+  private onResize: () => void = () => {}
+
+  start(onInput: (data: string) => void, onResize: () => void): void {
+    this.started += 1
+    this.onInput = onInput
+    this.onResize = onResize
+  }
+
+  stop(): void {
+    this.stopped += 1
+  }
+
+  write(data: string): void {
+    this.output += data
+  }
+
+  moveBy(lines: number): void {
+    this.output += `[move:${lines}]`
+  }
+
+  hideCursor(): void {
+    this.output += '[hide]'
+  }
+
+  showCursor(): void {
+    this.output += '[show]'
+  }
+
+  clearLine(): void {
+    this.output += '[clear-line]'
+  }
+
+  clearFromCursor(): void {
+    this.output += '[clear-rest]'
+  }
+
+  clearScreen(): void {
+    this.output += '[clear-screen]'
+  }
+
+  setTitle(title: string): void {
+    this.title = title
+  }
+
+  setProgress(active: boolean): void {
+    this.progress.push(active)
+  }
+
+  send(data: string): void {
+    this.onInput(data)
+  }
+
+  resize(columns: number, rows = this.rows): void {
+    this.columns = columns
+    this.rows = rows
+    this.onResize()
+  }
+}
+
+interface FakeAgent extends Agent {
+  status: AgentStatus
+  sent: ContentBlock[][]
+  steered: ContentBlock[][]
+  cancelled: string[]
+}
+
+async function tick(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 25))
+}
+
+async function setup(options: {
+  status?: AgentStatus
+  config?: Config
+  tools?: Record<string, ToolDefinition>
+  beforeMount?: (session: Session) => void
+  cwd?: string | null
+} = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  const tools = options.tools ?? {}
+  ctx.provide('tools', {
+    get(name: string) {
+      return tools[name]
+    },
+  } as never)
+  const session = ctx.sessions.create(
+    SessionId('main-session'),
+    options.cwd === null ? undefined : { meta: { cwd: options.cwd ?? process.cwd() } },
+  )
+  options.beforeMount?.(session)
+  const sent: ContentBlock[][] = []
+  const steered: ContentBlock[][] = []
+  const cancelled: string[] = []
+  const agent: FakeAgent = {
+    id: AgentId('main'),
+    options: { model: 'deepseek-v4-flash' },
+    session,
+    status: options.status ?? 'idle',
+    ctx,
+    sent,
+    steered,
+    cancelled,
+    send(content) {
+      sent.push(content)
+    },
+    steer(content) {
+      steered.push(content)
+    },
+    inject() {},
+    cancel(reason) {
+      cancelled.push(reason ?? '')
+    },
+    whenIdle() {
+      return Promise.resolve()
+    },
+  }
+  ctx.agents.register(agent)
+  const terminal = new FakeTerminal()
+  const exit = vi.fn()
+  const controller = createTuiChat(ctx, Object.assign({
+    welcome: 'Coding agent ready.',
+    agent: 'main',
+    color: false,
+  }, options.config), { terminal, exit })
+  await tick()
+  return { ctx, session, agent, terminal, exit, controller }
+}
+
+async function dispose(setupResult: Awaited<ReturnType<typeof setup>>): Promise<void> {
+  await setupResult.controller.dispose()
+  await setupResult.ctx.fiber.dispose()
+}
+
+function appendUser(session: Session, text: string): void {
+  session.append('user/message', {
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+function appendAssistant(session: Session, content: ContentBlock[], usage?: { inputTokens: number; outputTokens: number }): void {
+  session.append('assistant/message', {
+    turn: 1,
+    step: 0,
+    content,
+    ...usage === undefined ? {} : { usage },
+  }, { surfaceOp: 'append' })
+}
+
+describe('TUI config', () => {
+  it('defaults every direct-call TUI option', () => {
+    expect(resolveTuiConfig(undefined)).toEqual({
+      showReasoning: true,
+      maxToolOutputLines: 12,
+      maxQuestionOptions: 8,
+      questionDialogWidth: 72,
+      questionDialogMaxHeight: 20,
+      showHardwareCursor: false,
+      color: true,
+      title: 'DeepSeek Harness',
+    })
+    expect(resolveTuiConfig({
+      showReasoning: false,
+      maxToolOutputLines: 2,
+      maxQuestionOptions: 3,
+      questionDialogWidth: 60,
+      questionDialogMaxHeight: 14,
+      showHardwareCursor: true,
+      color: false,
+      title: 'DSH',
+    })).toEqual({
+      showReasoning: false,
+      maxToolOutputLines: 2,
+      maxQuestionOptions: 3,
+      questionDialogWidth: 60,
+      questionDialogMaxHeight: 14,
+      showHardwareCursor: true,
+      color: false,
+      title: 'DSH',
+    })
+  })
+})
+
+describe('pi-tui chat lifecycle and transcript', () => {
+  it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
+    const result = await setup({
+      beforeMount(session) {
+        appendUser(session, 'restored prompt')
+        appendAssistant(session, [
+          { type: 'reasoning', text: 'restored thought' },
+          { type: 'text', text: '**restored answer**' },
+        ], { inputTokens: 1_250, outputTokens: 42 })
+        session.append('todo/write', {
+          todos: [
+            { content: 'read code', status: 'completed' },
+            { content: 'write tests', status: 'in_progress' },
+            { content: 'ship', status: 'pending' },
+          ],
+        })
+      },
+    })
+
+    expect(result.terminal.started).toBe(1)
+    expect(result.terminal.title).toBe('DeepSeek Harness')
+    expect(result.terminal.output).toContain('DEEPSEEK')
+    expect(result.terminal.output).toContain('Coding agent ready.')
+    expect(result.terminal.output).toContain('restored prompt')
+    expect(result.terminal.output).toContain('restored thought')
+    expect(result.terminal.output).toContain('restored answer')
+    expect(result.terminal.output).toContain('write tests')
+    expect(result.terminal.output).toContain('↑1.3k ↓42')
+
+    result.agent.status = 'running'
+    result.ctx.emit('agent/status', result.agent, 'running')
+    result.session.append('user/message', { content: [{ type: 'text', text: '   ' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: 'steering note' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('context/message', { content: [{ type: 'text', text: 'user context' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('context/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('prompt/blocked', { content: [{ type: 'text', text: 'blocked' }], source: { kind: 'user' }, reason: 'test policy' })
+    appendAssistant(result.session, [])
+    result.session.append('turn/end', { turn: 9, reason: { kind: 'aborted' } })
+    result.session.append('turn/end', { turn: 10, reason: { kind: 'completed' } })
+    result.session.append('step/start', { turn: 11, step: 0 })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-start', index: 0, blockType: 'reasoning' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'reasoning-delta', index: 0, text: 'live thought' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'reasoning-delta', index: 9, text: 'unannounced thought' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'live thought complete' } },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-start', index: 1, blockType: 'text' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'text-delta', index: 1, text: 'live answer' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-end', index: 1, block: { type: 'text', text: 'live answer done' } },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-start', index: 2, blockType: 'tool-call' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'block-end', index: 2, block: { type: 'tool-call', id: 'stream-tool' as never, name: 'tool', arguments: '{}' } },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'tool-call-delta', index: 2, id: 'stream-tool' as never, argumentsDelta: '{}' },
+    })
+    result.session.append('assistant/chunk', {
+      turn: 2,
+      step: 0,
+      chunk: { type: 'usage', usage: { inputTokens: 1, outputTokens: 2 } },
+    })
+    await tick()
+    expect(result.terminal.output).toContain('live thought')
+    result.terminal.send('\x12')
+    await tick()
+    appendAssistant(result.session, [{ type: 'text', text: 'final live answer' }], { inputTokens: 500, outputTokens: 8 })
+    await tick()
+
+    expect(result.terminal.output).toContain('Working')
+    expect(result.terminal.output).toContain('Steering')
+    expect(result.terminal.output).toContain('user context')
+    expect(result.terminal.output).toContain('Prompt blocked')
+    expect(result.terminal.output).toContain('Turn cancelled')
+    expect(result.terminal.output).toContain('final live answer')
+    expect(result.terminal.output).toContain('↑1.8k ↓50')
+    expect(result.terminal.progress).toContain(true)
+
+    result.session.append('assistant/chunk', {
+      turn: 3,
+      step: 0,
+      chunk: { type: 'text-delta', index: 0, text: 'cleared stream' },
+    })
+    result.terminal.send('/clear')
+    result.terminal.send('\r')
+    appendAssistant(result.session, [{ type: 'text', text: 'answer after clear' }])
+    await tick()
+    expect(result.terminal.output).toContain('answer after clear')
+
+    result.agent.status = 'idle'
+    result.ctx.emit('agent/status', result.agent, 'idle')
+    await tick()
+    expect(result.terminal.progress.at(-1)).toBe(false)
+    await dispose(result)
+    expect(result.terminal.stopped).toBe(1)
+    expect(result.terminal.drainInput).toHaveBeenCalledWith(100, 20)
+  })
+
+  it('renders the ANSI palette and every markdown/content style', async () => {
+    const result = await setup({
+      config: { color: true },
+      beforeMount(session) {
+        session.append('user/message', {
+          content: [
+            { type: 'text', text: '# Heading\n\n[link](https://example.com) `code`\n\n```ts\nconst x = 1\n```\n\n> quote\n\n---\n\n- item\n\n**bold** *italic* ~~strike~~' },
+            { type: 'tool-call', id: 'nested' as never, name: 'nested_tool', arguments: '{}' },
+            { type: 'tool-result', toolCallId: 'nested' as never, content: [{ type: 'reasoning', text: 'nested result' }] },
+            { type: 'future-block' } as never,
+            {} as never,
+          ],
+          source: { kind: 'user' },
+        }, { surfaceOp: 'append' })
+        appendAssistant(session, [
+          { type: 'reasoning', text: 'styled reasoning' },
+          { type: 'text', text: 'styled answer' },
+        ], { inputTokens: 2_000_000, outputTokens: 1_500_000 })
+        session.append('todo/write', { todos: [
+          { content: 'done', status: 'completed' },
+          { content: 'active', status: 'in_progress' },
+          { content: 'later', status: 'pending' },
+        ] })
+      },
+    })
+    result.terminal.send('/')
+    await tick()
+    result.terminal.send('zz')
+    await tick()
+    result.terminal.send('\x0c')
+    await tick()
+
+    expect(result.terminal.output).toContain('\x1b[')
+    expect(result.terminal.output).toContain('Heading')
+    expect(result.terminal.output).toContain('nested_tool({})')
+    expect(result.terminal.output).toContain('nested result')
+    expect(result.terminal.output).toContain('[future-block]')
+    expect(result.terminal.output).toContain('[content]')
+    expect(result.terminal.output).toContain('↑2.0m ↓1.5m')
+    await dispose(result)
+  })
+
+  it('suppresses stale replay chunks and does not duplicate editor history on rebuild', async () => {
+    const result = await setup({
+      beforeMount(session) {
+        appendUser(session, 'first prompt')
+        appendUser(session, 'second prompt')
+        session.append('assistant/chunk', {
+          turn: 2,
+          step: 0,
+          chunk: { type: 'text-delta', index: 0, text: 'stale partial response' },
+        })
+      },
+    })
+
+    expect(result.terminal.output).not.toContain('stale partial response')
+    result.terminal.send('/reasoning')
+    result.terminal.send('\r')
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\r')
+    expect(result.agent.sent).toEqual([[{ type: 'text', text: 'first prompt' }]])
+    await dispose(result)
+  })
+
+  it('formats large token totals and cwd variants', async () => {
+    const homeResult = await setup({
+      cwd: process.env.HOME ?? process.cwd(),
+      beforeMount(session) {
+        appendAssistant(session, [{ type: 'text', text: 'home' }], { inputTokens: 25_000, outputTokens: 10_000 })
+      },
+    })
+    expect(homeResult.terminal.output).toContain('~  ↑25k ↓10k')
+    await dispose(homeResult)
+
+    const unsetResult = await setup({ cwd: null })
+    expect(unsetResult.terminal.output).toContain('cwd unset')
+    await dispose(unsetResult)
+
+    const outsideResult = await setup({ cwd: '/opt' })
+    expect(outsideResult.terminal.output).toContain('/opt')
+    await dispose(outsideResult)
+  })
+
+  it('sends, steers, handles commands, global keys, and disposed-agent input', async () => {
+    const result = await setup()
+
+    result.terminal.send('do the work')
+    result.terminal.send('\r')
+    expect(result.agent.sent).toEqual([[{ type: 'text', text: 'do the work' }]])
+
+    result.terminal.send('   ')
+    result.terminal.send('\r')
+
+    result.agent.status = 'running'
+    result.terminal.send('steer it')
+    result.terminal.send('\r')
+    expect(result.agent.steered).toEqual([[{ type: 'text', text: 'steer it' }]])
+
+    result.terminal.send('\x1b')
+    result.terminal.send('\x04')
+    result.terminal.send('\x03')
+    result.terminal.send('\x12')
+    result.terminal.send('\x0f')
+    result.terminal.send('/cancel')
+    result.terminal.send('\r')
+    expect(result.agent.cancelled).toContain('cancelled from terminal')
+
+    result.agent.status = 'idle'
+    for (const command of ['/help', '/reasoning', '/tools', '/redraw']) {
+      result.terminal.send(command)
+      result.terminal.send('\r')
+      await tick()
+    }
+    for (const command of ['/clear', '/cancel', '/wat']) {
+      result.terminal.send(command)
+      result.terminal.send('\r')
+    }
+    await tick()
+    result.terminal.send('draft')
+    result.terminal.send('\x03')
+    result.terminal.send('\x04')
+    await tick()
+
+    expect(result.terminal.output).toContain('Keyboard shortcuts')
+    expect(result.terminal.output).toContain('Reasoning blocks')
+    expect(result.terminal.output).toContain('Tool cards')
+    expect(result.terminal.output).toContain('already idle')
+    expect(result.terminal.output).toContain('Unknown command')
+    expect(result.exit).toHaveBeenCalledWith(0)
+    await result.controller.dispose()
+    await result.ctx.fiber.dispose()
+
+    const ctrlCExit = await setup()
+    ctrlCExit.terminal.send('\x03')
+    await tick()
+    expect(ctrlCExit.exit).toHaveBeenCalledWith(0)
+    await ctrlCExit.controller.dispose()
+    await ctrlCExit.ctx.fiber.dispose()
+
+    const disposedAgent = await setup()
+    disposedAgent.agent.status = 'disposed'
+    disposedAgent.terminal.send('late input')
+    disposedAgent.terminal.send('\r')
+    await tick()
+    expect(disposedAgent.terminal.output).toContain('is disposed')
+    await dispose(disposedAgent)
+  })
+
+  it('cancels before /exit while running and handles agent errors/disposal', async () => {
+    const result = await setup({ status: 'running' })
+    result.terminal.send('/exit')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.agent.cancelled).toContain('terminal exit requested')
+    expect(result.exit).toHaveBeenCalledWith(0)
+
+    const events = await setup()
+    const unrelatedSession = events.ctx.sessions.create(SessionId('unrelated-session'))
+    const unrelatedAgent = { ...events.agent, id: AgentId('unrelated'), session: unrelatedSession }
+    unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] })
+    events.ctx.emit('agent/status', unrelatedAgent, 'running')
+    events.ctx.emit('agent/error', unrelatedAgent, 1, 1, new Error('hidden error'))
+    events.ctx.emit('agent/disposed', unrelatedAgent)
+    events.ctx.emit('agent/error', events.agent, 3, 2, new Error('live failure'))
+    events.session.append('turn/end', { turn: 3, reason: { kind: 'error', step: 2, message: 'live failure' } })
+    events.session.append('turn/end', { turn: 4, reason: { kind: 'error', step: 1, message: 'durable failure' } })
+    events.session.append('turn/end', { turn: 5, reason: { kind: 'aborted', reason: 'stopped' } })
+    events.session.append('turn/end', { turn: 6, reason: { kind: 'max-tokens' } })
+    events.session.append('turn/end', { turn: 7, reason: { kind: 'rejected', reason: 'policy' } })
+    events.session.append('turn/end', { turn: 8, reason: { kind: 'interrupted' } })
+    events.ctx.emit('agent/disposed', events.agent)
+    await tick()
+    expect(events.terminal.output).toContain('live failure')
+    expect(events.terminal.output).toContain('durable failure')
+    expect(events.terminal.output).toContain('stopped')
+    expect(events.terminal.output).toContain('output-token limit')
+    expect(events.terminal.output).toContain('Turn rejected')
+    expect(events.terminal.output).toContain('previous process ended')
+    expect(events.terminal.output).toContain('was disposed')
+    await dispose(events)
+  })
+})
+
+describe('tool cards and surface replay', () => {
+  const tools: Record<string, ToolDefinition> = {
+    bash: {
+      name: 'bash', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'terminal', title: 'printf hello', description: 'Run command', cwd: '/tmp' }),
+      presentResult: () => ({ card: 'terminal', output: 'hello\nworld\nthird', exitCode: 0 }),
+    },
+    signal: {
+      name: 'signal', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'terminal', title: 'sleep 10' }),
+      presentResult: () => ({ card: 'terminal', signal: 'SIGTERM' }),
+    },
+    edit: {
+      name: 'edit', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({
+        card: 'diff',
+        title: 'Edit files',
+        diffs: [
+          { path: 'a.txt', oldText: 'old', newText: 'new' },
+          { path: 'b.txt', oldText: 'before', newText: 'after' },
+        ],
+      }),
+      presentResult: () => ({ card: 'diff', diffs: [{ path: 'a.txt', oldText: null, newText: 'created' }] }),
+    },
+    generic: {
+      name: 'generic', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'generic', title: 'Inspect value', rawInput: { alpha: 1 } }),
+      presentResult: () => ({ card: 'generic', title: 'Inspected', content: [{ type: 'text', text: 'result text' }] }),
+    },
+    throwing: {
+      name: 'throwing', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => { throw new Error('call presenter boom') },
+      presentResult: () => { throw new Error('result presenter boom') },
+    },
+    rawTerminal: {
+      name: 'rawTerminal', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'terminal', title: 'raw command' }),
+    },
+    undefinedViews: {
+      name: 'undefinedViews', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => undefined,
+      presentResult: () => undefined,
+    },
+    empty: {
+      name: 'empty', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'generic', title: 'Empty card' }),
+    },
+    terminalResult: {
+      name: 'terminalResult', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'generic', title: 'Becomes terminal' }),
+      presentResult: () => ({ card: 'terminal', output: 'converted terminal' }),
+    },
+    symbolic: {
+      name: 'symbolic', description: '', parameters: {}, execute: async () => [],
+      presentCall: () => ({ card: 'generic', title: 'Symbol input', rawInput: Symbol('input') }),
+    },
+  }
+
+  it('uses terminal, diff, generic, fallback, and collapsed tool presentations', async () => {
+    const result = await setup({ tools, config: { maxToolOutputLines: 1 } })
+    const calls = [
+      ['c1', 'bash', '{"command":"printf hello"}'],
+      ['c2', 'signal', '{}'],
+      ['c3', 'edit', '{}'],
+      ['c4', 'generic', '{}'],
+      ['c5', 'throwing', '{}'],
+      ['c6', 'unknown', 'not-json'],
+      ['c7', 'rawTerminal', '{"value":"raw"}'],
+      ['c8', 'undefinedViews', '{"value":8}'],
+      ['c10', 'empty', '{}'],
+      ['c11', 'terminalResult', '{}'],
+      ['c12', 'symbolic', '{}'],
+    ] as const
+    appendAssistant(result.session, [
+      { type: 'text', text: 'Calling tools' },
+      ...calls.map(([id, name, args]) => ({
+        type: 'tool-call' as const, id: id as never, name, arguments: args,
+      })),
+    ])
+    for (const [id, name, args] of calls) {
+      result.session.append('tool/call', { turn: 1, step: 0, callId: id as never, name, arguments: args })
+    }
+    await tick()
+    expect(result.terminal.output).toContain('$ raw command')
+    result.terminal.send('/reasoning')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('call presenter boom')
+    expect(result.terminal.output).toContain('Symbol(input)')
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c1' as never, content: [{ type: 'text', text: 'raw bash' }], isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c2' as never, content: [{ type: 'text', text: 'stopped' }], isError: true,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c3' as never, content: [{ type: 'text', text: 'done' }], isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c4' as never, content: [{ type: 'text', text: 'raw generic' }], isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c5' as never, content: [{ type: 'text', text: 'raw throwing' }], isError: false,
+      meta: { value: 1 },
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c7' as never,
+      content: [
+        { type: 'tool-call', id: 'inner' as never, name: 'inner', arguments: '{}' },
+        { type: 'tool-result', toolCallId: 'inner' as never, content: [{ type: 'text', text: 'nested output' }] },
+        { type: 'future-result' } as never,
+      ],
+      isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c8' as never, content: [{ type: 'text', text: '\nundefined presenter output\n\nkept tail\n' }], isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'c11' as never, content: [{ type: 'text', text: '\nconverted terminal\n\nfinished\n' }], isError: false,
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'orphan' as never, content: [{ type: 'text', text: 'orphan result' }], isError: false,
+    }, { surfaceOp: 'append' })
+    await tick()
+
+    const output = result.terminal.output
+    expect(output).toContain('Run command')
+    expect(output).toContain('printf hello')
+    expect(output).toContain('more lines')
+    expect(output).toContain('SIGTERM')
+    expect(output).toContain('Edit files')
+    expect(output).toContain('Inspected')
+    expect(output).toContain('result text')
+    expect(output).toContain('Presenter failed')
+    expect(output).toContain('not-json')
+    expect(output).toContain('nested output')
+    expect(output).toContain('[future-result]')
+    expect(output).toContain('undefined presenter output')
+    expect(output).toContain('Empty card')
+    expect(output).toContain('converted terminal')
+    expect(output).toContain('orphan result')
+
+    result.terminal.send('/redraw')
+    result.terminal.send('\r')
+    await tick()
+    result.terminal.send('\x0f')
+    await tick()
+    expect(result.terminal.output).toContain('world')
+    expect(result.terminal.output).toContain('+ created')
+    await dispose(result)
+  })
+
+  it('rebuilds after a surface replacement and hides shadowed tool calls', async () => {
+    const result = await setup({ tools })
+    appendUser(result.session, 'old prompt')
+    const assistant = result.session.append('assistant/message', {
+      turn: 1,
+      step: 0,
+      content: [{ type: 'tool-call', id: 'old-call' as never, name: 'bash', arguments: '{}' }],
+    }, { surfaceOp: 'append' })
+    result.session.append('tool/call', {
+      turn: 1, step: 0, callId: 'old-call' as never, name: 'bash', arguments: '{}',
+    })
+    const toolResult = result.session.append('tool/result', {
+      turn: 1, step: 0, callId: 'old-call' as never, content: [{ type: 'text', text: 'old output' }], isError: false,
+    }, { surfaceOp: 'append' })
+    const start = result.session.surface.nodes[0]?.seq as number
+    result.session.append('context/message', {
+      content: [{ type: 'text', text: 'summary replacement' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }, {
+      surfaceOp: { op: 'replace', start, end: toolResult.seq },
+      sourceEventSeqs: [start, assistant.seq, toolResult.seq],
+    })
+    await tick()
+
+    result.terminal.resize(89)
+    await tick()
+    const lastFullRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
+    expect(lastFullRender).toContain('summary replacement')
+    expect(lastFullRender).not.toContain('old output')
+    await dispose(result)
+  })
+})
+
+describe('TUI user-interaction dialogs', () => {
+  it('answers single-select, multi-select, custom, and optionless questions', async () => {
+    const result = await setup({ config: { maxQuestionOptions: 1 } })
+
+    const single = result.ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode', header: 'Mode', question: 'Choose a mode',
+        options: [{ label: 'Safe', description: 'Use checks' }, { label: 'Fast' }],
+      }],
+    })
+    await tick()
+    expect(result.terminal.output).toContain('Choose a mode')
+    expect(result.terminal.output).toContain('1/2')
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\r')
+    await expect(single).resolves.toEqual({ answers: [{ id: 'mode', selected: ['Fast'] }] })
+
+    const multi = result.ctx.userInteraction.ask({
+      questions: [{ id: 'targets', question: 'Pick targets', multiSelect: true, options: [{ label: 'Code' }, { label: 'Docs' }] }],
+    })
+    await tick()
+    result.terminal.send(' ')
+    result.terminal.send('\x1b[B')
+    result.terminal.send(' ')
+    result.terminal.send('\r')
+    await expect(multi).resolves.toEqual({ answers: [{ id: 'targets', selected: ['Code', 'Docs'] }] })
+
+    const custom = result.ctx.userInteraction.ask({
+      questions: [{ id: 'other', question: 'Choose or type', options: [{ label: 'Default' }] }],
+    })
+    await tick()
+    result.terminal.send('c')
+    result.terminal.send('my choice')
+    result.terminal.send('\r')
+    await expect(custom).resolves.toEqual({ answers: [{ id: 'other', selected: [], custom: 'my choice' }] })
+
+    const free = result.ctx.userInteraction.ask({ questions: [{ id: 'note', question: 'Add a note' }] })
+    await tick()
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Enter an answer before submitting')
+    result.terminal.send('ship it')
+    result.terminal.send('\r')
+    await expect(free).resolves.toEqual({ answers: [{ id: 'note', selected: [], custom: 'ship it' }] })
+    await dispose(result)
+  })
+
+  it('handles option wrapping, deselection errors, and returning from custom input', async () => {
+    const result = await setup({ config: { color: true } })
+    const single = result.ctx.userInteraction.ask({
+      questions: [{ id: 'single', question: 'Single options', options: [{ label: 'One' }, { label: 'Two' }] }],
+    })
+    const singleRejected = expect(single).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await tick()
+    expect(result.terminal.output).toContain('Two')
+    result.terminal.send('\x03')
+    await singleRejected
+
+    const answer = result.ctx.userInteraction.ask({
+      questions: [{
+        id: 'options',
+        question: 'Exercise options',
+        multiSelect: true,
+        options: [{ label: 'One', description: 'first' }, { label: 'Two' }],
+      }],
+    })
+    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await tick()
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\x1b[A')
+    result.terminal.send(' ')
+    await tick()
+    result.terminal.send('x')
+    result.terminal.send(' ')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Select at least one option')
+    result.terminal.send('c')
+    await tick()
+    result.terminal.send('\x1b')
+    await tick()
+    expect(result.terminal.output).toContain('Space toggle')
+    result.terminal.send('\x03')
+    await rejected
+    await dispose(result)
+  })
+
+  it('asks batches in order and rejects cancelled or aborted work', async () => {
+    const result = await setup()
+    const preAborted = new AbortController()
+    preAborted.abort()
+    await expect(result.ctx.userInteraction.ask({
+      questions: [{ id: 'pre-aborted', question: 'Already cancelled?' }],
+      signal: preAborted.signal,
+    })).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+
+    const batch = result.ctx.userInteraction.ask({
+      questions: [
+        { id: 'first', question: 'First?', options: [{ label: 'Yes' }] },
+        { id: 'second', question: 'Second?' },
+      ],
+    })
+    await tick()
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Second?')
+    result.terminal.send('done')
+    result.terminal.send('\r')
+    await expect(batch).resolves.toEqual({ answers: [
+      { id: 'first', selected: ['Yes'] },
+      { id: 'second', selected: [], custom: 'done' },
+    ] })
+
+    const cancelled = result.ctx.userInteraction.ask({ questions: [{ id: 'cancel', question: 'Cancel?' }] })
+    const cancelledExpectation = expect(cancelled).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await tick()
+    result.terminal.send('\x1b')
+    await cancelledExpectation
+
+    const controller = new AbortController()
+    const active = result.ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }], signal: controller.signal })
+    const queuedController = new AbortController()
+    const queued = result.ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }], signal: queuedController.signal })
+    const activeExpectation = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    const queuedExpectation = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await tick()
+    queuedController.abort()
+    controller.abort()
+    await activeExpectation
+    await queuedExpectation
+    await dispose(result)
+  })
+
+  it('rejects active and queued dialogs on disposal', async () => {
+    const result = await setup()
+    const active = result.ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
+    const queued = result.ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
+    const activeExpectation = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    const queuedExpectation = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await tick()
+    await result.controller.dispose()
+    await activeExpectation
+    await queuedExpectation
+    await expect(result.ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Late?' }] }))
+      .rejects.toMatchObject({ code: 'NO_PROVIDER' })
+    await result.ctx.fiber.dispose()
+  })
+})
+
+describe('terminal mounting', () => {
+  it('starts immediately when the configured agent already exists', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    ctx.provide('tools', { get: () => undefined } as never)
+    const session = ctx.sessions.create(SessionId('mounted-session'))
+    ctx.agents.register({
+      id: AgentId('main'), options: {}, session, status: 'idle', ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    })
+    const terminal = new FakeTerminal()
+    mountTui(ctx, { color: false }, { terminal, exit: vi.fn() })
+    await tick()
+    expect(terminal.started).toBe(1)
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for its configured agent before starting the TUI', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    ctx.provide('tools', { get: () => undefined } as never)
+    const terminal = new FakeTerminal()
+    mountTui(ctx, { agent: 'main', color: false }, { terminal, exit: vi.fn() })
+    expect(terminal.started).toBe(0)
+
+    const otherSession = ctx.sessions.create(SessionId('other-session'))
+    ctx.agents.register({
+      id: AgentId('other'), options: {}, session: otherSession, status: 'idle', ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    })
+    expect(terminal.started).toBe(0)
+
+    const session = ctx.sessions.create(SessionId('late-session'))
+    const agent = {
+      id: AgentId('main'), options: {}, session, status: 'idle', ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    } as Agent
+    ctx.agents.register(agent)
+    await tick()
+    expect(terminal.started).toBe(1)
+    await ctx.fiber.dispose()
+  })
+
+  it('rolls back providers, listeners, and terminal state when startup fails', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    ctx.provide('tools', { get: () => undefined } as never)
+    const session = ctx.sessions.create(SessionId('failed-start-session'))
+    ctx.agents.register({
+      id: AgentId('main'), options: {}, session, status: 'running', ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    })
+    const terminal = new FakeTerminal()
+    terminal.start = () => { throw new Error('terminal startup failed') }
+
+    expect(() => createTuiChat(ctx, { color: false }, { terminal, exit: vi.fn() }))
+      .toThrow('terminal startup failed')
+    expect(terminal.stopped).toBe(1)
+    expect(terminal.progress).toEqual([false, true, false])
+    await expect(ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Late?' }] }))
+      .rejects.toMatchObject({ code: 'NO_PROVIDER' })
+    session.append('assistant/chunk', {
+      turn: 1,
+      step: 0,
+      chunk: { type: 'text-delta', index: 0, text: 'must not render' },
+    })
+    await tick()
+    expect(terminal.output).not.toContain('must not render')
+    await ctx.fiber.dispose()
+  })
+
+  it('throws when createTuiChat is called without the configured agent', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    ctx.provide('tools', { get: () => undefined } as never)
+    const runtime: TuiRuntime = { terminal: new FakeTerminal(), exit: vi.fn() }
+    expect(() => createTuiChat(ctx, { agent: 'missing' }, runtime)).toThrow('is not running')
+    await ctx.fiber.dispose()
+  })
+})
--- a/packages/ui/tui/tsconfig.json
+++ b/packages/ui/tui/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": "../../core/tools"
+    },
+    {
+      "path": "../user-interaction"
+    }
+  ]
+}
--- a/packages/ui/user-interaction/README.md
+++ b/packages/ui/user-interaction/README.md
@@ -21,7 +21,7 @@ When an answer includes `custom`, `selected` is empty; custom text is an overrid

 ## Role

-This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; UI front doors such as the `stdio-agent` readline module and the `acp` bridge provide the provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.
+This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; UI front doors such as the interactive `dsh-tui`, line-oriented `dsh-stdio`, and structured `dsh-acp` channels provide the provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.

 ## Model Experience