diff --git a/AGENTS.md b/AGENTS.md
index 60763520ce..a0ef9c7539 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,7 +27,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code / Codex hook bridges + shared wire-protocol library
   session-persistence/  persistence seam + JSONL/SQLite backends
-  ui/          ACP/stdio/JSON-RPC bridges; boot, approval, interaction plugins
+  ui/          ACP/stdio/TUI/JSON-RPC bridges; boot, approval, interaction plugins
   examples/    demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure packages
   util/        zero-dependency utilities
@@ -58,6 +58,7 @@ pnpm run doc-sync       # all documentation gates; see the doc-sync script in pa
 pnpm run website:build  # VitePress build (doubles as the site's dead-link check)
 pnpm run demo:echo      # mock-model REPL, no key needed
 pnpm run demo:repl      # real REPL coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # self-referential demo: the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP server agent (needs DEEPSEEK_API_KEY)
 ```
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 790812344d..19c4ccf72d 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 53dd3896eb15800125673e7c44f7de02daca9376
-README.zh.md: ab826f62658248249ec18c57b35c0065c0f909d1
+README.md: aaa129272ee9346cebe2d59774d742fbe21af80a
+README.zh.md: 42f2ed9b57bf008210042083977b7adbb7f1ab0e
diff --git a/README.md b/README.md
index 53dd3896eb..aaa129272e 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,10 @@ This monorepo is built on the [Cordis](https://github.com/cordiverse/cordis) fra
 ```sh
 pnpm install
 pnpm run test          # vitest
-pnpm run demo:repl     # REPL agent demo (needs DEEPSEEK_API_KEY)
+pnpm run demo:echo     # keyless mock-model REPL
+pnpm run demo:repl     # readline coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:tui      # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:cordis   # self-referential agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```
 
diff --git a/README.zh.md b/README.zh.md
index ab826f6265..42f2ed9b57 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -11,7 +11,10 @@
 ```sh
 pnpm install
 pnpm run test          # vitest
-pnpm run demo:repl     # REPL agent demo (needs DEEPSEEK_API_KEY)
+pnpm run demo:echo     # keyless mock-model REPL
+pnpm run demo:repl     # readline coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:tui      # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:cordis   # self-referential agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```
 
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 0c305e87c8..dc06018c16 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -27,7 +27,7 @@ Placement: bugs → postmortems; rationale → RFCs; procedures → cookbooks; t
 - **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, RFCs, or postmortems.
 - **Write an RFC in the same PR for decisions a maintainer may reasonably revisit.** Mechanical or self-evident changes need none ([when to write one](rfc/README.md)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
-- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type definition is fenced ` ```ts type-equiv ` and registered in the manifest so it cannot drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc are fenced ` ```ts type-equiv ` and registered in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
 - **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, conditions, timing, modality, exceptions, consequences, and non-obvious orientation; delete implementation narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link to its owning rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage, decision rules, and examples.
diff --git a/docs/architecture.md b/docs/architecture.md
index 2f47722ba7..09cc43afeb 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -151,7 +151,7 @@ Some seams bend the template deliberately: LLM combines interface and consumer b
 
 ### Bundles And Apps
 
-`dsh-agent-spine-demo` bundles the default spine ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-stdio-demo` adds a terminal front door; `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` bundles the default spine ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-stdio-demo` adds a terminal front door that selects `dsh-tui` for interactive terminals and line-oriented `dsh-stdio` for pipes; `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
 
 ### Where New Behavior Goes
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 82e9573df7..feb31a358e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -79,7 +79,6 @@ flowchart LR
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
   pkg_subagent_acp["subagent-acp"]
-  pkg_subagent_mock["subagent-mock"]
   pkg_tasks["tasks"]
   svc_tasks["ctx.tasks<br/>Background task registry"]
   pkg_tool_tasks["tool-tasks"]
@@ -132,7 +131,6 @@ flowchart LR
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
   pkg_subagent_fork --> svc_subagents
-  pkg_subagent_mock --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_system_prompt --> svc_systemPrompt
   pkg_tasks --> svc_tasks
@@ -229,7 +227,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. |
 | `ctx.tasks` | `core` | [`tasks`](../packages/tasks/tasks) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (tool-bash background commands, tool-subagent background delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7c16d90e4f..ee6003c6f6 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -787,7 +787,7 @@ Source: [`packages/ui/stdio/src/index.ts:33`](../packages/ui/stdio/src/index.ts)
  * 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 {
   /** Provider route for the `main` agent. */
@@ -808,6 +808,8 @@ export interface Config {
   persistenceRoot?: string
   /** stdin-chat 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. */
@@ -823,11 +825,22 @@ export interface Config {
   /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
   workspaceContext: agentCore.Config['workspaceContext']
 }
+
+/** 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
+}
+
+/** Terminal front door selected by the app bundle. */
+export type TerminalMode = 'auto' | 'readline' | 'tui'
 ```
 
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts)
 
-Source: [`packages/examples/stdio-demo/src/index.ts:40`](../packages/examples/stdio-demo/src/index.ts)
+Source: [`packages/examples/stdio-demo/src/index.ts:75`](../packages/examples/stdio-demo/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-acp`
 
@@ -890,41 +903,6 @@ export interface Config {
 
 Source: [`packages/subagent/subagent-fork/src/index.ts:25`](../packages/subagent/subagent-fork/src/index.ts)
 
-## `@deepseek-ai/dsh-subagent-mock`
-
-Requires: `subagents`
-
-```ts config-catalog
-/** Config for the mock provider; all optional with test-friendly defaults. */
-export interface Config {
-  /** Registry name to register under. */
-  name: string
-  /** The text the scripted child "returns" as its final answer. */
-  reply?: string
-  /** The stop reason the run settles with. */
-  stopReason?: SubagentStopReason
-  /** Which start-time capabilities to advertise (default: all `true`). */
-  capabilities?: Partial<SubagentCapabilities>
-  /**
-   * The conversation-history descriptor to declare
-   * ({@link SubagentProvider.inheritsParentContext}); default `false` (fresh
-   * conversation). Set `true` to exercise seeded/fork wording in consumer
-   * tests. This flag says nothing about tool, service, scope, or authority
-   * inheritance.
-   */
-  inheritsParentContext?: boolean
-  /**
-   * Structured value surfaced when a request carries an `outputSchema` and the
-   * `outputSchema` capability is on (default: `{ reply }`).
-   */
-  structured?: unknown
-}
-```
-
-Depends on: [`SubagentCapabilities`](../packages/subagent/subagent/src/index.ts) · [`SubagentStopReason`](../packages/subagent/subagent/src/index.ts)
-
-Source: [`packages/support/subagent-mock/src/index.ts:87`](../packages/support/subagent-mock/src/index.ts)
-
 ## `@deepseek-ai/dsh-subagent-spawn`
 
 Requires: `subagents`
@@ -1206,6 +1184,42 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
 
 Source: [`packages/core/tools/src/index.ts:382`](../packages/core/tools/src/index.ts)
 
+## `@deepseek-ai/dsh-tui`
+
+Requires: `agents` · `userInteraction` · `tools`
+
+```ts config-catalog
+/** Serializable plugin configuration. */
+export interface Config extends TuiConfig {
+  /** Header subtitle. Defaults to `ready.`. */
+  welcome?: string
+  /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
+  sessionId?: string
+}
+
+/** Presentation settings for the pi-tui terminal mode. */
+export interface TuiConfig {
+  /** Render model reasoning blocks. */
+  showReasoning?: boolean
+  /** Maximum tool-output lines shown before the card is collapsed. */
+  maxToolOutputLines?: number
+  /** Maximum options visible at once in a user-question dialog. */
+  maxQuestionOptions?: number
+  /** User-question dialog width in terminal columns. */
+  questionDialogWidth?: number
+  /** User-question dialog maximum height in terminal rows. */
+  questionDialogMaxHeight?: number
+  /** Show the terminal's hardware cursor at the pi editor's IME marker. */
+  showHardwareCursor?: boolean
+  /** Apply the built-in ANSI color palette. */
+  color?: boolean
+  /** Terminal window title while the UI is mounted. */
+  title?: string
+}
+```
+
+Source: [`packages/ui/tui/src/index.ts:100`](../packages/ui/tui/src/index.ts)
+
 ## `@deepseek-ai/dsh-user-approval`
 
 ```ts config-catalog
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index b44b0e51b4..241ab178a4 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-extension-cookbook.md: 995ecd879faec02044b55ce3d53f7fe1b2aed270
-extension-cookbook.zh.md: e3fe3103e13c359e77e0202df223aae35bcdd525
+extension-cookbook.md: 1a1f0b200801a54f067faf9866b72ccadfdc62d3
+extension-cookbook.zh.md: 891a808b4ed87b1fd92d0b68c580895956f9ab8c
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 995ecd879f..1a1f0b2008 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -87,7 +87,7 @@ export function apply(ctx: Context) {
 
 ## Runnable wirings
 
-Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite behind a terminal REPL UI, `pnpm run demo:repl`), and [`examples/acp-agent`](../../examples/acp-agent) (an agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the ACP demo loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle.
+Five runnable leaves load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + coding tools through a line-oriented readline REPL, `pnpm run demo:repl`), [`examples/tui-agent`](../../examples/tui-agent) (the same coding composition through full-screen pi-tui, `pnpm run demo:tui`), [`examples/cordis-agent`](../../examples/cordis-agent) (self-inspection and dynamic plugin mounting, `pnpm run demo:cordis`), and [`examples/acp-agent`](../../examples/acp-agent) (an ACP server over JSON-RPC stdio, `pnpm run demo:acp`). The terminal leaves load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the ACP leaf loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and both app packages share the spine through [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).
 
 ## The feature → mechanism map
 
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index e3fe3103e1..891a808b4e 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -87,7 +87,7 @@ export function apply(ctx: Context) {
 
 ## 可运行的组装示例
 
-三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app 包入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，ACP 演示加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，两个 app 包通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle 共享主干。
+五个可运行叶子从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + coding 工具，通过面向行的 readline REPL 交互，`pnpm run demo:repl`）、[`examples/tui-agent`](../../examples/tui-agent)（通过全屏 pi-tui 复用相同的 coding 组装，`pnpm run demo:tui`）、[`examples/cordis-agent`](../../examples/cordis-agent)（自我检查和动态插件挂载，`pnpm run demo:cordis`）与 [`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露的 ACP 服务器，`pnpm run demo:acp`）。终端叶子加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，ACP 叶子加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，两个 app 包通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 共享主干。
 
 ## 功能→机制映射
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 4a19b57af5..4598390194 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -257,7 +257,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
-Source: [`packages/core/session/src/index.ts:46`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:47`](../../packages/core/session/src/index.ts)
 
 ### `session/disposed` — emit
 
@@ -267,7 +267,7 @@ Emitted once when an announced session leaves the store, including publication r
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
-Source: [`packages/core/session/src/index.ts:56`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts)
 
 ### `session/event` — emit
 
@@ -279,7 +279,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 
 Types: [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:68`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:69`](../../packages/core/session/src/index.ts)
 
 ### `session/flush` — parallel
 
@@ -289,7 +289,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
-Source: [`packages/core/session/src/index.ts:78`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:79`](../../packages/core/session/src/index.ts)
 
 ## `subagent/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 99107c061a..40bd029e41 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -238,7 +238,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Source: [`packages/core/session/src/index.ts:585`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:577`](../../packages/core/session/src/index.ts)
 
 ## `ctx.skills` — `SkillService`
 
diff --git a/docs/core-data-structures/approval.md b/docs/core-data-structures/approval.md
index e8820ccfeb..8634415a62 100644
--- a/docs/core-data-structures/approval.md
+++ b/docs/core-data-structures/approval.md
@@ -9,12 +9,20 @@ Source: [`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approv
 Every request receives a fresh `ApprovalRequestId`. The brand pairs the `approval/asked` and `approval/decided` audit events without making approval ids interchangeable with tool-call or agent/session ids.
 
 ```ts type-equiv
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
 type ApprovalRequestId = Branded<'ApprovalRequestId'>
 ```
 
 `ApprovalOutcome` is closed and fail-closed. `allowed-once` grants only the asked-about action; callers deny on `rejected`, `cancelled`, and `unavailable`. A missing, non-owning, throwing, or non-conforming answerer becomes `unavailable` rather than opening the gate.
 
 ```ts type-equiv
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
 type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
 ```
 
@@ -23,6 +31,18 @@ type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
 `ApprovalPolicy` determines what happens before interactive answerers run. `ask` delegates to the composed answerer chain, whose no-answer default is `unavailable`; `never` deterministically returns `rejected` without dispatching any answerer. The effective value is the last `approval/policy` event in the session log, falling back to the service config. `setApprovalPolicy(session, policy)` is the single write path, so replay reconstructs the override.
 
 ```ts type-equiv
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`
+ *   (exactly today's behavior).
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the only policy value stated in the system prompt — unlike `'ask'`, its
+ *   outcome is knowable without asking, so stating it cannot overclaim.
+ */
 type ApprovalPolicy = 'ask' | 'never'
 ```
 
@@ -33,6 +53,10 @@ The prompt section states the deterministic `never` behavior and records either
 `ApprovalRequest` identifies the agent and tool action closely enough to route and audit the question. It deliberately omits tool arguments: an answerer attaches the prompt to the already-streamed tool call through `callId` instead of rendering a second copy that could drift.
 
 ```ts type-equiv
+/**
+ * Readonly same-process permission question. `callId` links to an already
+ * presented tool call, so arguments are not duplicated here.
+ */
 interface ApprovalRequest {
   /**
    * The agent on whose behalf the question is asked. Routes the question (a
diff --git a/docs/core-data-structures/bash.md b/docs/core-data-structures/bash.md
index c61c24add6..060d249eb7 100644
--- a/docs/core-data-structures/bash.md
+++ b/docs/core-data-structures/bash.md
@@ -9,10 +9,12 @@ Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.t
 `DSH_*` variables are Harness-owned child-process facts. The model-facing bash tool collects them through `ctx.bashEnv` and passes them through `BashExecRequest.dshEnv`; executors remove inherited `DSH_*` names before merging the current snapshot.
 
 ```ts type-equiv
+/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
 type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`
 ```
 
 ```ts type-equiv
+/** Trusted DeepSeek Harness variables for one bash execution. */
 type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>
 ```
 
@@ -21,6 +23,12 @@ type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>
 The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package seams" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
 
 ```ts type-equiv
+/**
+ * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
+ * filled by {@link BashExecutor.resolve} from the implementation's config.
+ * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
+ * fully-resolved {@link BashExecSpec}.
+ */
 interface BashExecRequest {
   command: string
   /** Working directory override (default: implementation-configured). */
@@ -59,24 +67,17 @@ interface BashExecRequest {
    * reject non-`DSH_*` names supplied through this managed channel.
    */
   dshEnv?: DshEnvironment | undefined
-  /**
-   * Explicit per-call sandbox-policy input, overriding the executor's
-   * configured default mode for THIS call. Never a silent default: a
-   * consumer sets it only from an explicit policy source — an
-   * `'allowed-once'` grant a human just issued through `ctx.approval` (the
-   * escalation flow in the sandbox RFC § Escalation, which outranks), or the
-   * session's standing override folded from its own `bash/sandbox-mode`
-   * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session
-   * choice). A sandboxing executor confines THIS call under the given mode;
-   * a non-sandboxing executor carries the field and confines nothing (the
-   * tool layer stamps neither escalation nor overrides without a sandboxing
-   * executor — see {@link BashExecutor.sandboxMode}).
-   */
+  /** Explicit per-call sandbox mode override. */
   sandboxMode?: SandboxMode | undefined
 }
 ```
 
 ```ts type-equiv
+/**
+ * A resolved execution spec. {@link BashExecutor.resolve} fills and caps the
+ * required fields; {@link BashExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
+ */
 interface BashExecSpec {
   command: string
   workdir: string
@@ -88,31 +89,18 @@ interface BashExecSpec {
   stdoutMaxBytes: number
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the command's stdin (then close it), carried through
-   * verbatim from {@link BashExecRequest.stdin}. It has no config default, so
-   * a missing value means "no stdin" and remains an ordinary optional.
-   */
+  /** Bytes to write to stdin before closing it; absent means no stdin. */
   stdin?: string | undefined
   /**
-   * Extra environment entries, carried through verbatim from
-   * {@link BashExecRequest.env} and merged by the implementation AFTER its
-   * credential scrub (an explicit entry wins even when its name matches the
-   * scrub pattern). OPTIONAL on the spec for the same reason as `stdin` — no
-   * config default, absent means "no extra env".
+   * Ordinary environment entries carried through from
+   * {@link BashExecRequest.env}. `DSH_*` remains reserved for {@link dshEnv}.
+   * OPTIONAL on the spec for the same reason as `stdin`: absent means no
+   * ordinary extra environment.
    */
   env?: Record<string, string> | undefined
   /** Managed `DSH_*` snapshot; implementations reject ordinary names. */
   dshEnv?: DshEnvironment | undefined
-  /**
-   * The sandbox mode this call executes under, required-but-nullable so every
-   * resolved spec states its policy. A sandboxing executor's `resolve()` stamps
-   * the effective mode (the request's explicit override, else its configured
-   * default) so `run()`/`start()` read the spec, never the config;
-   * a non-sandboxing executor carries the request value through verbatim and
-   * ignores it (`undefined` under such an executor means what its README says:
-   * unconfined execution).
-   */
+  /** Resolved sandbox mode; ignored by executors that do not confine. */
   sandboxMode: SandboxMode | undefined
 }
 ```
@@ -126,24 +114,31 @@ interface BashExecSpec {
 The outcome of one completed (or killed) foreground run. Orthogonal outcomes are reported **independently** — a process can both time out AND exit 0 because it trapped the signal — so `timedOut`, `aborted`, `signal`, and `exitCode` are each their own field; a caller never reads a cut-short run as a clean success.
 
 ```ts type-equiv
+/** The outcome of one completed (or killed) foreground run. */
 interface BashRunResult {
   /** Exit code; null when the process died from a signal. */
   exitCode: number | null
   /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
   signal: NodeJS.Signals | null
-  /** True when the executor's own timeout killed the command. */
+  /**
+   * True when the executor's own timeout was the FIRST cause to cut the command
+   * short. Mutually exclusive with {@link aborted}: one fused deadline drives
+   * both the timeout and the caller's cancellation, so a timeout and an abort
+   * racing before process close report the single first-abort cause, not both
+   * (see the [timeout-library RFC](../../../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+   */
   timedOut: boolean
-  /** True when the caller's AbortSignal killed the command. */
+  /**
+   * True when the caller's `AbortSignal` was the FIRST cause to kill the command
+   * (and it was not the executor's own timeout). Mutually exclusive with
+   * {@link timedOut} — see there for the first-cause classification.
+   */
   aborted: boolean
   /** The effective timeout applied to this run (after defaulting/capping). */
   timeoutMs: number
   stdout: CollectedOutput
   stderr: CollectedOutput
-  /**
-   * Sandbox facts, present iff a sandboxing executor ran the command — an
-   * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See
-   * {@link BashSandboxInfo} for the `denied` classification semantics.
-   */
+  /** Sandbox execution facts, absent for an unsandboxed executor. */
   sandbox?: BashSandboxInfo
 }
 ```
@@ -151,6 +146,7 @@ interface BashRunResult {
 Each stream is a `CollectedOutput` — the (possibly truncated) text plus recovery info. When truncated, `text` is the **tail** and the complete stream spills to a private file:
 
 ```ts type-equiv
+/** One captured stream: the (possibly truncated) text plus recovery info. */
 interface CollectedOutput {
   /** Collected text — the TAIL of the stream when truncated. */
   text: string
@@ -168,36 +164,19 @@ A sandbox-consuming executor exposes its configured fallback through `BashExecut
 A sandboxed run reports its mode, conservative denial classification, and enforcement completeness. `runnerFailed` marks a sandbox runner failure before the command ran; foreground execution throws `SANDBOX_UNAVAILABLE`, while a settled background process has only its facts channel.
 
 ```ts type-equiv
+/**
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
+ * Facts are reported independently of process exit status so callers can
+ * distinguish command failures from policy denials and runner failures.
+ */
 interface BashSandboxInfo {
   /** The mode the command actually ran under. */
   mode: SandboxMode
-  /**
-   * True when the executor classifies this run's failure as the sandbox
-   * denying a file operation. The classification is CONSERVATIVE (a failed
-   * exit whose stderr carries a filesystem-permission signature) and reads
-   * the COLLECTED stderr — the bounded in-memory tail per
-   * {@link CollectedOutput} semantics, so a signature that survives only in a
-   * spill file is missed toward `denied: false`. A plain command failure
-   * keeps `denied: false` even under a sandboxed mode.
-   */
+  /** Whether the sandbox denied a file operation. */
   denied: boolean
-  /**
-   * How completely the runner enforced `mode`'s file effects — see
-   * {@link SandboxEnforcement}. Absent exactly when `mode` is
-   * `danger-full-access`: nothing is confined, so there is no enforcement to
-   * report.
-   */
+  /** How completely the selected runner enforced the requested mode. */
   enforcement?: SandboxEnforcement
-  /**
-   * True when the executor classifies this failure as the SANDBOX RUNNER
-   * itself failing (missing binary, refused profile, fail-closed refusal
-   * before exec) — the command NEVER RAN; this is a sandbox failure, not a
-   * task failure, and it outranks `denied` (a runner's own error text can
-   * contain denial words). Only ever stamped on settled BACKGROUND tasks: a
-   * foreground run surfaces the same condition as the thrown
-   * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error
-   * channel; a settled task's facts are its only channel).
-   */
+  /** Whether the sandbox runner failed before the command could run. */
   runnerFailed?: boolean
 }
 ```
@@ -209,6 +188,11 @@ One more piece completes the vocabulary: the `SANDBOX_UNAVAILABLE` error code (o
 `start()` returns a handle with no id or owner. `dsh-tool-bash` adapts it into `ctx.tasks.start()` hooks; the generic runtime then owns task identity and lifecycle. `done` resolves when the process closes and never rejects, reads remain valid after settlement, and sandbox facts are stamped before `done` resolves.
 
 ```ts type-equiv
+/**
+ * A background process handle returned by {@link BashExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Executor
+ * disposal kills running processes and awaits {@link done}.
+ */
 interface BashProcess {
   /** Process lifecycle state (settled exactly once). */
   status: BashProcessStatus
@@ -237,6 +221,7 @@ interface BashProcess {
 `readOutput()` returns the incremental delta and spill recovery facts:
 
 ```ts type-equiv
+/** One incremental {@link BashProcess.readOutput} read. */
 interface BashProcessRead {
   /** Output produced since the previous read (stderr in a marked section). */
   delta: string
diff --git a/docs/core-data-structures/code-runtime.md b/docs/core-data-structures/code-runtime.md
index 9237a3cce9..cea69180af 100644
--- a/docs/core-data-structures/code-runtime.md
+++ b/docs/core-data-structures/code-runtime.md
@@ -9,6 +9,12 @@ Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-
 A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package seams" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
 
 ```ts type-equiv
+/**
+ * One run: the program source plus everything the runtime acts on. Per the
+ * explicit-over-implicit convention, defaulting (time budgets, output caps)
+ * is the implementation's validated config — a request carries no optional
+ * tuning knobs for a hidden `??` to fill in.
+ */
 interface CodeRunRequest {
   /**
    * The program source, in the runtime's {@link ../index.ts | language}. It
@@ -31,6 +37,11 @@ interface CodeRunRequest {
 The result reports an error as a **field**, never a rejection of `run()` — reporting a failed program is the caller's job, not an exception path (mirroring `BashExecutor.run`'s resolve-on-failure contract):
 
 ```ts type-equiv
+/**
+ * The outcome of one run. An error is a FIELD on a resolved result, never a
+ * rejection of `run()` — reporting a failed program is the caller's job, not
+ * an exception path.
+ */
 interface CodeRunResult {
   /**
    * The program's completion value (its top-level `return`), when it ran to
@@ -51,6 +62,13 @@ interface CodeRunResult {
 Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the Code Mode consumer passes one: `tools`). Arguments and resolutions must be structured-cloneable — a runtime may bridge calls across a serialization boundary — and a runtime treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
 
 ```ts type-equiv
+/**
+ * A named group of {@link CodeBindingFunction}s the runtime exposes to the
+ * program as one global object (e.g. `tools`). Function names are arbitrary
+ * strings — a runtime must treat names like `__proto__` or `constructor` as
+ * ordinary own properties (null-prototype construction), never as prototype
+ * collisions.
+ */
 interface CodeBindingNamespace {
   /** The global identifier the program sees (must be a valid JS identifier). */
   global: string
@@ -60,6 +78,14 @@ interface CodeBindingNamespace {
 ```
 
 ```ts type-equiv
+/**
+ * One host-side function exposed to the program as an async callable. The
+ * runtime bridges calls to it (possibly across a serialization boundary), so
+ * `args` and the resolution value MUST be structured-cloneable; a runtime
+ * rejects a non-cloneable value with a descriptive error rather than
+ * corrupting the run. A rejection of this function surfaces inside the
+ * program as a rejection of the corresponding call.
+ */
 type CodeBindingFunction = (args: unknown) => Promise<unknown>
 ```
 
@@ -70,6 +96,16 @@ Logs are plain strings in emission order. The runtime captures the program's con
 Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
 
 ```ts type-equiv
+/**
+ * Why a run failed. The kinds are orthogonal outcomes reported independently
+ * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * abort is not a timeout, and a substrate death is neither.
+ *
+ * - `'exception'` — the program threw or failed to parse/transform.
+ * - `'timeout'` — an implementation-owned budget expired; the message says which.
+ * - `'abort'` — {@link CodeRunRequest.signal} fired.
+ * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ */
 interface CodeRunFailure {
   /** The failure class (see the interface doc for each kind's meaning). */
   kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'
diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md
index 11f895b2a8..ccc212a895 100644
--- a/docs/core-data-structures/compaction.md
+++ b/docs/core-data-structures/compaction.md
@@ -23,6 +23,7 @@ These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` b
 What a successful compaction returns to its caller: the bookkeeping-event seqs, raw summary, shadowed range and seqs, and estimated token count.
 
 ```ts type-equiv
+/** Result of a successful compaction operation. */
 interface CompactionResult {
   /** The seq of the appended `compact/start` event. */
   startSeq: number
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 1e802f3630..9efe04e63c 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -36,7 +36,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
 
-> Type definitions on this page are pasted **verbatim** from source and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Inline JSDoc is omitted for readability; follow the source link for the full contracts.
+> Type declarations and their JSDoc on this page are pasted **verbatim** from source and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)).
 
 FIXME(catalog-verbs): the drift gate covers only the nouns (the pasted type shapes); every method surface on these pages is hand-written prose. core-data-structures should probably also generate the *verbs* — the public methods of the cataloged classes — so a signature change cannot silently outdate the catalog.
 
@@ -83,6 +83,7 @@ The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../..
 Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
 
 ```ts type-equiv
+/** A string carrying a compile-time-only brand `B`. */
 type Branded<B extends string> = string & { readonly [BRAND]: B }
 ```
 
@@ -95,6 +96,10 @@ A conversation is `Message`s; a message is an array of typed **content blocks**.
 Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
 ```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
 interface ContentBlockMap {
   'text': TextBlock
   'reasoning': ReasoningBlock
@@ -108,6 +113,7 @@ The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBl
 A `Message` is a role plus blocks. Loop-derived assistant messages carry their durable provider/model identity and optional adapter-private replay metadata:
 
 ```ts type-equiv
+/** Provider ownership and adapter-private replay data for an assistant message. */
 interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -123,6 +129,10 @@ interface AssistantProvenance {
 ```
 
 ```ts type-equiv
+/**
+ * A single message in a conversation history. Loop-derived assistant messages
+ * always carry provenance; callers may omit it on hand-built foreign history.
+ */
 interface Message {
   role: 'system' | 'user' | 'assistant'
   content: ContentBlock[]
@@ -134,6 +144,10 @@ interface Message {
 Where a message came from is itself a merge-extensible sum type:
 
 ```ts type-equiv
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
 interface MessageSourceMap {
   user: { kind: 'user' }
   plugin: { kind: 'plugin'; plugin: string }
@@ -155,6 +169,7 @@ Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 Provider and model discovery uses small provider-neutral descriptors. A model catalog is advisory: routing still keys on a registered provider, and an adapter may accept unlisted model ids.
 
 ```ts type-equiv
+/** Display metadata for one registered provider route. */
 interface LlmProviderInfo {
   /** Provider route key used by {@link GenerateOptions.provider}. */
   id: string
@@ -164,6 +179,7 @@ interface LlmProviderInfo {
 ```
 
 ```ts type-equiv
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
 interface LlmModelInfo {
   /** Provider route that owns this model entry. */
   provider: string
@@ -177,6 +193,7 @@ interface LlmModelInfo {
 ```
 
 ```ts type-equiv
+/** A single model request, fully assembled. */
 interface GenerateOptions {
   /** Registered provider route selecting the adapter instance. */
   provider: string
@@ -212,6 +229,10 @@ interface GenerateOptions {
 Why a model response stopped is a merge-extensible reason:
 
 ```ts type-equiv
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
 interface FinishReasonMap {
   'stop': { kind: 'stop' }
   'tool-calls': { kind: 'tool-calls' }
@@ -226,6 +247,13 @@ interface FinishReasonMap {
 `GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
 
 ```ts type-equiv
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
 interface ToolSchema {
   name: string
   description: string
@@ -247,6 +275,11 @@ On the wire, a loop-built request reads in this order: the `system` slot (the re
 FIXME(call-config-shape): revisit the exact definition of this type — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit here out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them.
 
 ```ts type-equiv
+/**
+ * Provider + model + sampling scalars of one conversation's requests. Every field maps
+ * 1:1 onto the same-named `GenerateOptions` field; the loop builds requests
+ * from the logged header rather than accepting these per call.
+ */
 interface LlmCallConfig {
   provider: string
   model: string
@@ -263,6 +296,19 @@ A `Session` is an **append-only log** of typed `SessionEvent`s — the single so
 Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
 
 ```ts type-equiv
+/**
+ * One immutable entry in the session log.
+ *
+ * A proper discriminated union over `type` (not independent `type`/`data`
+ * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
+ */
 type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
@@ -275,7 +321,9 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /**
      * Seq numbers of events that are provenance sources of this event
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node).
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -295,35 +343,29 @@ Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types
 `InjectOptions` extends ordinary message attribution with context-only framing and durable model-hidden JSON metadata:
 
 ```ts type-equiv
+/** Options specific to durable synthetic context injection. */
 interface InjectOptions extends SendOptions {
+  /** Keep the canonical context tag, or send caller-owned framing verbatim. */
   envelope?: ContextEnvelope
+  /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }
 ```
 
 ```ts type-equiv
+/** Public agent handle; its concrete implementation is internal to `@deepseek-ai/dsh-agent-loop`. */
 interface Agent {
+  /** The single identity shared with {@link session}. */
   readonly id: SessionId
   readonly options: AgentOptions
   readonly session: Session
   readonly status: AgentStatus
-
-  /**
-   * The agent's scope context (`@deepseek-ai/dsh-scope`, key = this agent):
-   * registrations through it — tools, prompt sections/variables, listeners,
-   * restrictions — are visible to this agent only and unwind when it is
-   * disposed; `agent.ctx.on('agent/…')` listeners fire only for this agent.
-   */
+  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
   /**
-   * Queue a user message. Starts a turn when idle; otherwise waits for the next
-   * turn. Content and the resolved source are accepted as one detached,
-   * deeply-frozen lossless-JSON record before notification or enqueue, so
-   * caller or `agent/queued` listener in-place mutation cannot change later
-   * log/model input. Throws synchronously when either value is not losslessly
-   * JSON-serializable; `agent/prompt-submit` may still return an explicit
-   * replacement.
+   * Queue detached, frozen lossless-JSON input; starts a turn when idle.
+   * Invalid input throws synchronously before notification or enqueue.
    */
   send(content: ContentBlock[], options?: SendOptions): void
 
@@ -335,77 +377,25 @@ interface Agent {
   steer(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Inject in-session context (file-change notices, skill content, cron
-   * notifications, …): appends a `context/message` session event the next model
-   * request sees at its chronological position, rendered as synthetic context
-   * rather than a user prompt. The default uses the canonical context tag;
-   * `options.envelope: 'raw'` preserves caller-owned framing. Does not run the
-   * model.
-   *
-   * In an open turn, inject appends at the current log position except while
-   * the current tool-call batch executes: accepted context waits FIFO until the
-   * batch settles, then appends after every recorded result and before turn
-   * close even when execution is interrupted.
-   *
-   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
-   * an inject while idle wraps its `context/message` in a one-shot `injection`
-   * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
-   * durability, so every event stays inside a turn and a persistence backend
-   * never loses a between-turn notice. The idle checkpoint is fire-and-forget
-   * (inject is synchronous): a failing flush is reported via `agent/error`
-   * (step `0`) and the logger, never thrown into the caller.
-   *
-   * Live-adapter review has validated the canonical tagged-envelope rendering
-   * against current DeepSeek behavior; provider-specific mismatches belong in
-   * that adapter, not in the canonical session vocabulary.
+   * Append detached model-facing context without running the model. An open-turn
+   * injection joins at the current log position unless the current tool batch is
+   * executing; then it waits FIFO until that batch settles and drains before turn
+   * close even when interrupted. Idle injection uses a one-shot turn and durability
+   * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`.
    */
   inject(content: ContentBlock[], options?: InjectOptions): void
 
   /**
-   * Cancel ALL pending work for the agent. `cancel()`:
-   *
-   * - clears the queued FIFO (un-started prompts never run) and the steering
-   *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
-   * - aborts the in-flight step if one is running (the turn ends `aborted`);
-   * - drops a turn that is about to start (a `cancel()` landing in the
-   *   pre-step window — after a `send()` queued but before the loop flips to
-   *   `running`, or after `running` is emitted but before the first step) so
-   *   that queued prompt does not run and cannot be batched into the cancelled
-   *   turn.
-   *
-   * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state.
-   * `cancel()` on an idle agent with nothing queued or running is a safe no-op
-   * — it does NOT arm anything that would drop a later legitimate prompt.
+   * Clear queued and steering work, including work waiting to start, and abort
+   * the active step. The supplied reason is preserved across pre-step and active
+   * cancellation windows, and `whenIdle()` resolves after cancellation reaches
+   * quiescence. Idle cancellation is a no-op and does not arm a later cancel.
    */
   cancel(reason?: string): void
 
-  /**
-   * Resolve once the agent has reached quiescence after settling out of
-   * `running`, or immediately if it is already idle with no queued work. A
-   * non-owner's quiescence-observation hook: a consumer that does NOT own the
-   * agent's lifecycle awaits this to proceed only after queued/running work has
-   * fully stopped, rather than returning while the driver is still streaming or
-   * about to start a queued turn — without itself tearing the agent down. (A
-   * lifecycle OWNER does not need it: `AgentHandle.dispose()` already awaits the
-   * loop-exit promise directly as part of stopping and unregistering. So this is
-   * for a non-owning observer — e.g. a test awaiting a turn to settle, or a
-   * monitor — that wants the settle signal but must not dispose the agent.)
-   *
-   * "Quiescence", not merely "status changed": a disposed agent emits
-   * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop
-   * has unwound — so `whenIdle()` resolving on `disposed` must wait for the loop
-   * to actually exit (the implementation chains the loop-exit promise), not just
-   * observe the status flip. A mid-step disposal that never reaches `idle` still
-   * unblocks the await this way.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
-  // Subagent delegation is realized on top of this interface by the
-  // `@deepseek-ai/dsh-subagent` seam, not by a method here: a backend creates
-  // the child through `ctx.agents.create` (fork seeds the child Session with a
-  // balanced prefix of the parent's log via `CreateAgentOptions.seed`; spawn
-  // starts fresh) and drives it as an ordinary Agent handle, so steer() and
-  // event subscription work uniformly. See docs/core-data-structures/subagent.md.
 }
 ```
 
@@ -464,10 +454,13 @@ Each `agent/*` interception waterfall returns a small, seam-specific typed union
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
+/** Model-facing context injected by a listener; `source` prevents plugin text from being labeled as user input. */
 interface HookContext {
   content: ContentBlock[]
   source: MessageSource
+  /** Keep the canonical context tag, or use caller-owned framing verbatim. */
   envelope?: ContextEnvelope
+  /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }
 ```
@@ -475,6 +468,11 @@ interface HookContext {
 `agent/prompt-submit` returns a `PromptDecision` (allow a drained queued message — optionally rewriting its `content` or attaching `additionalContexts` — or block it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`):
 
 ```ts type-equiv
+/**
+ * Prompt interception result. `allow.content` replaces the prompt and each
+ * `additionalContexts` entry becomes a separate context message. `block` records a
+ * durable `prompt/blocked`; an all-blocked batch ends a zero-step rejected turn.
+ */
 type PromptDecision =
   | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
   | { kind: 'block'; reason: string }
@@ -483,6 +481,7 @@ type PromptDecision =
 `agent/turn-continuation` returns a `ContinuationDecision` (the loop's default is `continue` when the step had tool calls or steering was injected, else `stop`; a `continue` `reason` is recorded as next-step steering in the same turn and therefore carries no context envelope or metadata — the typed `/goal` pattern):
 
 ```ts type-equiv
+/** Turn continuation override; a continue reason is recorded as next-step steering in the same turn. */
 type ContinuationDecision =
   | { action: 'stop' }
   | { action: 'continue'; reason?: { content: ContentBlock[]; source: MessageSource } }
@@ -491,12 +490,18 @@ type ContinuationDecision =
 `agent/turn-stop` returns the stop-only `ContinuationStop` subset or `undefined`. The loop calls this serial checkpoint after folding the ordinary decision, its reason, and pending steering; a stop is terminal and discards pending steering.
 
 ```ts type-equiv
+/**
+ * The terminal subset of {@link ContinuationDecision}. A listener on
+ * `agent/turn-stop` returns this to make the already-composed continuation
+ * outcome terminal; `undefined` abstains.
+ */
 type ContinuationStop = Extract<ContinuationDecision, { action: 'stop' }>
 ```
 
 `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
 
 ```ts type-equiv
+/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
 type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 ```
 
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 6438b1ba03..f29258857e 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -11,8 +11,17 @@ Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.
 Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
 
 ```ts type-equiv
+/**
+ * A path resolved by a backend into a stable identity. `resolve()` produces
+ * this; every other operation takes it.
+ */
 interface FsTarget {
+  /** Opaque key for stale guards and target lookup. */
   targetKey: FsTargetKey
+  /**
+   * Path for model/UI-facing output. May be a local absolute path,
+   * workspace-relative path, or remote URI depending on the backend.
+   */
   displayPath: string
 }
 ```
@@ -20,19 +29,40 @@ interface FsTarget {
 The backend owns file-version tokens — the freshness token a write/edit guards against. The policy plugin stores them for stale checks; consumers do not interpret them. Both ids are branded opaque strings.
 
 ```ts type-equiv
+/**
+ * Opaque key for stale guards and target lookup. The local backend uses a
+ * realpath-like string; a remote backend might use a workspace URI or file id.
+ * Consumers MUST NOT parse it or assume it is a local absolute path.
+ */
 type FsTargetKey = Branded<'FsTargetKey'>
 ```
 
 ```ts type-equiv
+/**
+ * Opaque file-version token — the freshness token a write/edit guards against.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
+ */
 type FsVersion = Branded<'FsVersion'>
 ```
 
 `stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure.
 
 ```ts type-equiv
+/**
+ * Metadata about a target — what {@link FileSystem.stat} returns. Lets the
+ * policy layer reject directories/special files before reading and choose
+ * `readText` vs `streamText` from `size` without probing by failure. `version`
+ * is the freshness token. `undefined` from `stat` means the target is absent.
+ */
 interface FsInfo {
+  /** Opaque freshness token of the target right now. */
   version: FsVersion
+  /** Whether the target is a regular file, a directory, or something else. */
   type: 'file' | 'directory' | 'other'
+  /** Byte size of a regular file, when the backend can report it. */
   size?: number
 }
 ```
@@ -40,9 +70,18 @@ interface FsInfo {
 `lstat` is the path-level no-follow metadata primitive. It takes a path instead of an `FsTarget` because `resolve` intentionally follows symlinks to produce stable identity; consumers that need trust-boundary checks can call `lstat` first and reject `symlink` before resolving.
 
 ```ts type-equiv
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
 interface FsPathInfo {
+  /** Opaque freshness token of the path entry right now. */
   version: FsVersion
+  /** Whether the path entry is a regular file, directory, symlink, or other. */
   type: 'file' | 'directory' | 'symlink' | 'other'
+  /** Byte size of the path entry, when the backend can report it. */
   size?: number
 }
 ```
@@ -50,11 +89,20 @@ interface FsPathInfo {
 `listDir` returns direct child entries in stable name order. Each entry carries the child basename, type, resolved target, and cheap metadata when the backend can report it. It must not read file contents, so `size` is only for regular files and `version` is metadata-derived. Broken or disappeared children may be returned as `other` without metadata; permission or backend I/O failures while listing or resolving child metadata fail the whole listing with `FS_PERMISSION_DENIED` or `FS_IO_ERROR`.
 
 ```ts type-equiv
+/**
+ * One direct child returned by {@link FileSystem.listDir}. Listing returns
+ * metadata and resolved targets only; it must not read file contents.
+ */
 interface FsDirEntry {
+  /** Basename of the child inside the listed directory. */
   name: string
+  /** Whether the child is a regular file, a directory, or something else. */
   type: 'file' | 'directory' | 'other'
+  /** Resolved child target for follow-up operations. */
   target: FsTarget
+  /** Opaque freshness token when the backend can report metadata cheaply. */
   version?: FsVersion
+  /** Byte size of a regular file, when the backend can report it. */
   size?: number
 }
 ```
@@ -64,16 +112,33 @@ interface FsDirEntry {
 Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
 
 ```ts type-equiv
+/**
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
+ */
 type FsWriteIntent =
   | { kind: 'createIfAbsent' }
   | { kind: 'replaceIfVersion'; version: FsVersion }
 ```
 
 ```ts type-equiv
+/** Outcome of a full-file write. */
 interface FsWriteOutcome {
+  /** Whether the write created a new file or replaced an existing one. */
   operation: 'create' | 'update'
+  /** Opaque version of the file after the write. */
   version: FsVersion
+  /**
+   * The file's content BEFORE the write, or `null` when the file did not exist
+   * (a create) or was undiffable (binary/non-UTF-8). LF-normalized storage text
+   * (the diff basis), never a diff — a consumer computes the result-time
+   * contextual diff from `before`/`after` when `before` is present, else falls
+   * back to a whole-file diff.
+   */
   before: string | null
+  /** The file's content AFTER the write, LF-normalized to share `before`'s diff basis. */
   after: string
 }
 ```
@@ -81,17 +146,29 @@ interface FsWriteOutcome {
 `editText` is a provider-level mutation, not a `read` plus `write` composed elsewhere. When guarded it verifies the expected version BEFORE literal matching (so a stale edit reports `FS_STALE_VERSION`, not a match failure against newer content); unguarded it edits the current content. Either way it applies the replacement and writes atomically — keeping matching, line-ending handling, the stale check, and atomic replacement inside one mutation critical section — and a missing target reports `FS_STALE_VERSION` on both paths.
 
 ```ts type-equiv
+/** A literal-replacement edit request. */
 interface FsEditRequest {
+  /** Literal non-empty text to replace. Must match exactly (after line-ending normalization). */
   oldString: string
+  /** Literal replacement text. An empty string deletes the matched text. */
   newString: string
+  /** Replace every match instead of requiring exactly one. */
   replaceAll: boolean
 }
 ```
 
 ```ts type-equiv
+/** Outcome of a literal edit. */
 interface FsEditOutcome {
+  /** Opaque version of the file after the edit. */
   version: FsVersion
+  /**
+   * The file's content BEFORE the edit. Raw storage text (LF-normalized by the
+   * backend), never a diff — a consumer computes the result-time contextual diff
+   * (the applied hunk with context) from `before`/`after`.
+   */
   before: string
+  /** The file's content AFTER the edit. */
   after: string
 }
 ```
@@ -107,8 +184,20 @@ interface FsEditOutcome {
 The policy plugin needs just enough execution context to derive the observed-state owner by narrowing the opaque `object` actor the `fs/*` events carry. `ToolExecution` satisfies this shape, so `dsh-tool-fs` passes its execution object through as the actor without making `dsh-fs-policy` import the tool, agent, or session packages.
 
 ```ts type-equiv
+/**
+ * Minimal structural view of a tool execution the policy plugin needs to derive
+ * an observed-state owner. `@deepseek-ai/dsh-tools`' `ToolExecution` satisfies
+ * this shape, so the tool passes its `exec` straight through as the opaque
+ * `object` actor on the `fs/*` events; this plugin narrows that actor to this
+ * shape without importing `dsh-tools`, `dsh-agent`, or `dsh-session`.
+ *
+ * The owner is `agent.session` when present. It is treated as an opaque object
+ * identity (a `WeakMap` key); this package never reads any of its fields.
+ */
 interface FsPolicyExec {
+  /** The agent on whose behalf the call runs, when there is one. */
   agent?: {
+    /** The session that owns observed-file state, used as an opaque key. */
     session?: object
   }
 }
@@ -119,10 +208,15 @@ interface FsPolicyExec {
 A text read is bounded by line window, byte cap, and backend limits. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits `fs/observed` with the stat's version directly), so any windowed read can authorize a later write/edit when the file is unchanged. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
 
 ```ts type-equiv
+/** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
 interface FileReadOutcome {
+  /** 1-based first line requested. */
   offset: number
+  /** Returned lines, already numbered. */
   lines: FileTextLine[]
+  /** Total line count in the file, unless `truncatedByBytes` stopped scanning early. */
   totalLines: number
+  /** Whether selected output hit the byte cap before EOF or the requested limit. */
   truncatedByBytes?: true
 }
 ```
@@ -136,6 +230,11 @@ Observed state is a `WeakMap<owner, Map<targetKey, { version }>>` held inside th
 Filesystem failures use stable `FsErrorCode` strings carried by `FsError` (`HarnessError`). The tool registry preserves `{ name, code }` on error results, so retry, permission, and UI layers can branch without parsing text.
 
 ```ts type-equiv
+/**
+ * Stable, machine-routable codes for filesystem failures. Carried on
+ * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * results so retry/permission/UI layers can branch without parsing messages.
+ */
 type FsErrorCode =
   | 'FS_NOT_FOUND'
   | 'FS_NOT_DIRECTORY'
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md
index f9489a6d7f..0ef9ae02f7 100644
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -9,6 +9,13 @@ Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
 
 ```ts type-equiv
+/**
+ * Raw streaming protocol emitted by adapters.
+ * Block indexes correlate interleaved deltas, and `block-end` carries the
+ * assembled block. Adapters emit usage before the terminal finish and nothing
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
+ */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
   | { type: 'text-delta'; index: number; text: string }
@@ -41,9 +48,19 @@ This contract was pinned down by two deliberately independent implementations: `
 The static public application identity every adapter sends to providers ([`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)). `attributionHeaders(identity?)` maps it to the standard `User-Agent` header only; OpenRouter-specific app attribution headers are intentionally not supported by this contract. The default `APP_IDENTITY` sources its version from the package manifest; every field is a public product fact - no secrets, paths, session ids, or per-user identifiers, and nothing per-request may influence the values. Rationale: [Mandatory `User-Agent` attribution](../rfc/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md).
 
 ```ts type-equiv
+/**
+ * Static public application identity sent to LLM providers.
+ *
+ * Every field is a public product fact, safe on every request: no secrets,
+ * local paths, session ids, prompt text, or per-user identifiers belong here,
+ * and nothing per-request may influence the values.
+ */
 interface AppIdentity {
+  /** `User-Agent` product token (lowercase, hyphenated). */
   product: string
+  /** Product version; sourced from package metadata, never hand-copied. */
   version: string
+  /** Public home URL of the app, used as the `User-Agent` comment. */
   url: string
 }
 ```
@@ -53,6 +70,14 @@ interface AppIdentity {
 Per-call token accounting. Counts are **disjoint**: `inputTokens` is uncached input only; cached input is reported separately, and billed input is the sum of the three. Adapters whose providers fold cache hits into a single prompt total (DeepSeek's `prompt_tokens`) subtract them back out.
 
 ```ts type-equiv
+/**
+ * Token accounting for one model call (cache fields are optional).
+ *
+ * Counts are DISJOINT: `inputTokens` is uncached input only; cached input is
+ * reported separately as `cacheReadTokens`/`cacheWriteTokens` (billed input =
+ * sum of the three). Adapters whose providers fold cache hits into a total
+ * prompt count (DeepSeek's `prompt_tokens`) subtract them out.
+ */
 interface TokenUsage {
   inputTokens: number
   outputTokens: number
@@ -73,6 +98,10 @@ interface TokenUsage {
 `ContentBlockType` (the key set the `index`-correlated blocks carry) derives from `ContentBlockMap`:
 
 ```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
 interface ContentBlockMap {
   'text': TextBlock
   'reasoning': ReasoningBlock
diff --git a/docs/core-data-structures/persistence.md b/docs/core-data-structures/persistence.md
index c1e02ae743..72ebcc5852 100644
--- a/docs/core-data-structures/persistence.md
+++ b/docs/core-data-structures/persistence.md
@@ -17,6 +17,11 @@ A backend that reloads a log crashed mid-turn finds an open `turn/start` with no
 `SessionPersistence.locate(meta)` synchronously resolves a backend-owned independent artifact without reading, creating, or flushing it. JSONL returns its absolute target path; SQLite returns `undefined` because sessions share one database. A returned path can therefore name a file that does not yet exist or lacks the current unflushed turn; it is a location hint, not authorization or a freshness guarantee.
 
 ```ts type-equiv
+/**
+ * A backend-resolved, per-session local artifact location. The path is an
+ * absolute target path and can name an artifact that has not materialized yet.
+ * Consumers must treat it as a location hint, never as an authorization token.
+ */
 interface SessionLocation {
   /** Backend-specific artifact kind, for example `jsonl`. */
   readonly kind: string
@@ -32,6 +37,9 @@ Per-session metadata travels **separately** from the event log: format version,
 Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
 
 ```ts type-equiv
+/**
+ * Immutable validated storage metadata, kept outside the conversation event log.
+ */
 interface SessionHeader {
   /**
    * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the
@@ -48,13 +56,8 @@ interface SessionHeader {
   /** The session this one was forked from (seed lineage), if any. */
   readonly parentSession?: SessionId
   /**
-   * How many leading events were INHERITED via a seed rather than produced by
-   * this session — the seed boundary. Set when a fork seeds a child with a
-   * prefix of the parent's log (= the seeded prefix length); absent/0 means the
-   * session produced all its own events. Persisted so a reload reconstructs the
-   * boundary instead of re-deriving it from the full stored log, and so a replay
-   * harness can skip the inherited prefix when deriving the child's OWN script
-   * (the seeded events are the parent's, not this child's model calls).
+   * How many leading events were inherited through a seed. Persisting this
+   * boundary lets resume and replay distinguish parent history from child work.
    */
   readonly seedLength?: number
 }
@@ -65,20 +68,17 @@ interface SessionHeader {
 Creating a `Session` through the store takes a `seed` (replay/fork an existing event log) and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller supplies the validated absolute `cwd`, the `parentSession` lineage, the `seedLength` seed boundary, and — only when reconstructing a persisted session — the original `createdAt` to preserve it.
 
 ```ts type-equiv
+/**
+ * Options for creating a {@link Session} via the store. `seed` replays/forks
+ * an existing event log; `meta` carries the caller-supplied storage fields the
+ * store folds into a {@link SessionHeader}.
+ */
 interface CreateSessionOptions {
   /** Events to seed the new session with (replay/fork). */
   readonly seed?: readonly SessionEvent[]
   /**
-   * Creation metadata. The store fills in `version`/`id` and defaults
-   * `createdAt` to now; the caller supplies the storage-level fields (validated
-   * absolute `cwd`, `parentSession` lineage, the seed boundary `seedLength`, and
-   * — when reconstructing a persisted session — the original `createdAt` to
-   * preserve it).
-   *
-   * `seedLength` is EXPLICIT, not inferred from `seed.length`: a reconstruction
-   * (resume/load) seeds the WHOLE stored log, so its `seed.length` is the full
-   * length, not the original boundary — the caller must pass the persisted
-   * boundary back. A fresh fork passes its actual seeded-prefix length.
+   * Storage metadata read once before publication. `seedLength` is explicit
+   * because a resumed seed contains the full stored log, not only its inherited prefix.
    */
   readonly meta?: {
     readonly cwd?: string
diff --git a/docs/core-data-structures/sandbox.md b/docs/core-data-structures/sandbox.md
index 6b7b212373..5b20febc3e 100644
--- a/docs/core-data-structures/sandbox.md
+++ b/docs/core-data-structures/sandbox.md
@@ -9,18 +9,30 @@ Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox
 `SandboxMode` governs filesystem effects only. `read-only` denies writes except the required `/dev/null` sink; `workspace-write` permits writes under the workspace root and the backend's promised temp area; `danger-full-access` bypasses confinement. Network and process visibility are outside this vocabulary.
 
 ```ts type-equiv
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
 type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
 ```
 
 Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`.
 
 ```ts type-equiv
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
 type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
 ```
 
 Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction.
 
 ```ts type-equiv
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
 type SandboxEnforcement = 'full' | 'partial'
 ```
 
@@ -29,6 +41,15 @@ type SandboxEnforcement = 'full' | 'partial'
 The policy is fully resolved and carried per call. This permits concurrent consumers and one-shot escalated retries to ask the same provider for different boundaries without mutating provider state.
 
 ```ts type-equiv
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is the consumer's
+ * explicit step (its config owns the fallback chain); the provider treats
+ * the policy as fully specified.
+ */
 interface SandboxPolicy {
   /** The file-effect mode this execution runs under. */
   mode: ConfinedSandboxMode
@@ -42,6 +63,11 @@ interface SandboxPolicy {
 `ConfinedArgv` is what the consumer spawns. Besides the replacement argv, it carries the backend's enforcement fact and two orthogonal stderr dialects. `denialSignatures` identify the confined command being blocked while the sandbox works correctly. `runnerFailureSignatures` identify the sandbox runner refusing or failing before it executes the command; consumers check these first and surface a sandbox infrastructure failure, never an ordinary task failure.
 
 ```ts type-equiv
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
 interface ConfinedArgv {
   /** The wrapped argv (runner, profile, separator, then the caller's argv). */
   argv: string[]
@@ -57,17 +83,9 @@ interface ConfinedArgv {
    */
   denialSignatures: readonly string[]
   /**
-   * How the RUNNER ITSELF failing identifies itself: case-insensitive stderr
-   * substrings produced when the sandbox binary is missing, refuses its
-   * profile, or fails closed before exec'ing the command (`bwrap: `,
-   * `landlock-run: `, `sandbox-exec: ` — each covers both the runner's own
-   * error prefix and the shell's runner-not-found message). ORTHOGONAL to
-   * {@link denialSignatures}: a denial is the confined COMMAND being blocked
-   * (the sandbox working as designed); a runner failure means the command
-   * NEVER RAN and must surface as a sandbox failure, not a task failure —
-   * consumers check these signatures FIRST (a runner's own error text may
-   * contain denial words, e.g. an unopenable grant root reporting
-   * `Permission denied`).
+   * Case-insensitive signatures for runner failure before command execution.
+   * Consumers check these before denial signatures: runner failure means the
+   * command never ran, while denial means confinement worked and blocked it.
    */
   runnerFailureSignatures: readonly string[]
 }
diff --git a/docs/core-data-structures/scope.md b/docs/core-data-structures/scope.md
index 66d5f40de9..d79f464b3e 100644
--- a/docs/core-data-structures/scope.md
+++ b/docs/core-data-structures/scope.md
@@ -9,12 +9,18 @@ Source: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index
 `ScopeKey` is an opaque object identity. The shipped loop uses the live `Agent` object as its own key, but the primitive never inspects the object.
 
 ```ts type-equiv
+/** An opaque, identity-compared scope key. */
 type ScopeKey = object
 ```
 
 `Scoped<T>` is the compile-time brand on the opaque routing receiver returned by `scopeTarget(base, key)`. Scope-filtered event declarations require this carrier as their `this` type, while the real event subject remains an explicit argument.
 
 ```ts type-equiv
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
 type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
 ```
 
@@ -23,9 +29,13 @@ type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
 `Scope` pairs the tagged registration context with two teardown surfaces. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
 
 ```ts type-equiv
+/** A minted registration scope and its quiescent disposal boundaries. */
 interface Scope {
+  /** Context through which scope-owned registrations are made. */
   ctx: Context
+  /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
   rawDispose: () => Promise<void> | void
+  /** Dispose every scope-owned registration; racing calls await the same completion. */
   dispose(): Promise<void>
 }
 ```
diff --git a/docs/core-data-structures/session-query.md b/docs/core-data-structures/session-query.md
index 86d2259f7f..4652358162 100644
--- a/docs/core-data-structures/session-query.md
+++ b/docs/core-data-structures/session-query.md
@@ -9,23 +9,34 @@ Source: [`packages/session-query/session-query/src/types.ts`](../../packages/ses
 `SessionRecord` is returned by the cross-corpus list. It exposes source availability independently from the cloned live-preferred header. `SessionEventRecord` is a lightweight raw-log projection; classification uses the same `foldSurface()` transitions as model-history derivation.
 
 ```ts type-equiv
-export type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
+/** Whether an event is current model context, replaced context, or raw-log-only. */
+type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
 ```
 
 ```ts type-equiv
-export interface SessionRecord {
+/** Lightweight identity and source availability for one logical session. */
+interface SessionRecord {
+  /** Cloned session header selected from the live-preferred corpus. */
   header: SessionHeader
+  /** Whether the id currently exists in `ctx.sessions`. */
   live: boolean
+  /** Whether the active persistence backend currently materializes the id. */
   persisted: boolean
 }
 ```
 
 ```ts type-equiv
-export interface SessionEventRecord {
+/** Lightweight metadata for one event within a logical session. */
+interface SessionEventRecord {
+  /** Session that owns the event. */
   sessionId: SessionId
+  /** Monotonic event seq within the session. */
   seq: number
+  /** Discriminant of the session event. */
   type: SessionEventType
+  /** Event timestamp in Unix epoch milliseconds. */
   time: number
+  /** Event placement in the folded session surface. */
   surface: SessionEventSurface
 }
 ```
@@ -35,24 +46,35 @@ export interface SessionEventRecord {
 `SessionLineageTrace` carries known parents in immediate-to-outward order and a forest of recursively nested direct descendants. The completeness discriminant makes a known root and a missing parent mutually exclusive.
 
 ```ts type-equiv
-export interface SessionLineageNode {
+/** Recursive descendant node in a session-lineage trace. */
+interface SessionLineageNode {
+  /** Detached logical-corpus record for this descendant. */
   session: SessionRecord
+  /** Direct children, each carrying its own recursive descendants. */
   descendants: SessionLineageNode[]
 }
 ```
 
 ```ts type-equiv
-export type SessionLineageTrace = {
+/** Known ancestry and descendants for one logical session. */
+type SessionLineageTrace = {
+  /** Detached record for the session that was traced. */
   target: SessionRecord
+  /** Known parents from the immediate parent outward. */
   ancestors: SessionRecord[]
+  /** Complete known descendant trees rooted at the target's direct children. */
   descendants: SessionLineageNode[]
 } & (
   | {
+    /** The complete parent chain is present in the logical corpus. */
     complete: true
+    /** Detached record at the top of the complete lineage. */
     root: SessionRecord
   }
   | {
+    /** The parent chain leaves the visible logical corpus. */
     complete: false
+    /** First parent id that is not present in the logical corpus. */
     unresolvedParentId: SessionId
   }
 )
@@ -63,20 +85,31 @@ export type SessionLineageTrace = {
 The request addresses one raw seq and optional neighboring counts. The result carries a `SessionHeader` rather than availability flags so a known live target can remain independent of persistence health.
 
 ```ts type-equiv
-export interface SessionEventReadRequest {
+/** Request for one event plus raw neighboring log context. */
+interface SessionEventReadRequest {
+  /** Session that owns the target event. */
   sessionId: SessionId
+  /** Target event seq. */
   seq: number
+  /** Number of preceding raw events to include. */
   before?: number
+  /** Number of following raw events to include. */
   after?: number
 }
 ```
 
 ```ts type-equiv
-export interface SessionEventWindow {
+/** Full target event and a bounded raw-log window. */
+interface SessionEventWindow {
+  /** Cloned header for the live-preferred source read. */
   session: SessionHeader
+  /** Full cloned target event. */
   target: SessionEvent
+  /** Full cloned events from `startSeq` through `endSeq`. */
   events: SessionEvent[]
+  /** First seq included in `events`. */
   startSeq: number
+  /** Last seq included in `events`. */
   endSeq: number
 }
 ```
@@ -86,19 +119,29 @@ export interface SessionEventWindow {
 Event traces distinguish positional surface replacement from logged provenance. Every seq list contains direct links except `replacementChain`, which follows immediate replacers from the target to the final positional replacement.
 
 ```ts type-equiv
-export interface SessionEventTraceRequest {
+/** Request for direct surface and provenance relationships around one event. */
+interface SessionEventTraceRequest {
+  /** Session that owns the target event. */
   sessionId: SessionId
+  /** Target event seq. */
   seq: number
 }
 ```
 
 ```ts type-equiv
-export interface SessionEventTrace {
+/** Direct surface and provenance relationships for one event. */
+interface SessionEventTrace {
+  /** Lightweight target record. */
   target: SessionEventRecord
+  /** Immediate positional replacement event, when the target was shadowed. */
   replacedBy?: number
+  /** Positional replacers from the immediate replacement to the final replacement. */
   replacementChain: number[]
+  /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
+  /** Direct logged provenance sources in their recorded order. */
   sourceEventSeqs: number[]
+  /** Later events that directly name the target as a provenance source, in log order. */
   derivedEventSeqs: number[]
 }
 ```
@@ -108,7 +151,8 @@ export interface SessionEventTrace {
 The closed code union distinguishes request validation, missing targets, malformed surface logs, optional-backend failure, and contradictory source metadata.
 
 ```ts type-equiv
-export type SessionQueryErrorCode =
+/** Stable machine-routable failure taxonomy for exact session reads and traces. */
+type SessionQueryErrorCode =
   | 'SESSION_QUERY_EVENT_NOT_FOUND'
   | 'SESSION_QUERY_INVALID_CONFIG'
   | 'SESSION_QUERY_INVALID_LINEAGE'
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index 0e882bae33..3d3fca045a 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -9,6 +9,7 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
 `ContextEnvelope` selects the standard tagged projection or preserves a producer-owned complete frame. The latter changes framing only; the event remains a user-role `context/message` in chronological history.
 
 ```ts type-equiv
+/** Canonical context-tag framing, or caller-owned framing rendered verbatim. */
 type ContextEnvelope = 'context' | 'raw'
 ```
 
@@ -17,30 +18,43 @@ type ContextEnvelope = 'context' | 'raw'
 The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` provenance for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
 
 ```ts type-equiv
+/**
+ * The merge-extensible, append-only source of truth for an agent interaction.
+ * Message history is derived from this log. Every event is lossless JSON and
+ * sequence numbers stay contiguous, including raw chunks, so persistence can
+ * store the canonical log verbatim.
+ */
 interface SessionEventMap {
+  /**
+   * Opens turn `turn`. `trigger` records what started it — a drained message
+   * batch or an idle-time injection. The turn is the durability/replay
+   * boundary: every event sits between a `turn/start` and its matching
+   * `turn/end` (the turn-enclosure invariant).
+   */
   'turn/start': { turn: number; trigger: TurnTrigger }
+  /**
+   * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop
+   * fires the awaited `session/flush` checkpoint at every turn end, so the turn
+   * boundary is also the durable-commit boundary.
+   */
   'turn/end': { turn: number; reason: TurnEndReason }
+  /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
   'step/start': { turn: number; step: number }
+  /** Closes step `step` of turn `turn`. */
   'step/end': { turn: number; step: number }
   /** A user-visible prompt (queued message drained at turn start). */
   'user/message': { content: ContentBlock[]; source: MessageSource }
   /**
-   * A queued prompt an `agent/prompt-submit` listener VETOED — the durable
-   * record of a blocked prompt and why. Appended in place of the `user/message`
-   * the prompt would have become, so the block survives replay even in a MIXED
-   * batch where another queued prompt is allowed (there the turn does not end
-   * `rejected`, so the boundary reason alone would not preserve it). `content`
-   * is the original prompt the listener rejected; `reason` is the veto text
-   * ({@link PromptDecision} `block.reason`). NOT a {@link SurfaceEventType}: a
-   * blocked prompt produces no LLM message and never reaches `deriveMessages()`.
+   * Durable record of a prompt veto and its reason. It is log-only: the blocked
+   * prompt never enters the model-visible surface, including in a mixed batch.
    */
   'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
   /**
    * In-session context injection (file-change notices, subdir AGENTS.md,
    * skill content, cron notifications, …). Rendered into the derived history
    * as synthetic context — NOT a user prompt. `envelope: 'raw'` lets a caller
-   * supply its own complete framing; `meta` is persisted JSON hidden from the
-   * model.
+   * own the complete model-facing frame; `meta` is durable JSON state omitted
+   * from the model projection.
    */
   'context/message': {
     content: ContentBlock[]
@@ -57,34 +71,29 @@ interface SessionEventMap {
    * usage record). `usage` is absent when the adapter reported none.
    */
   'assistant/message': { turn: number; step: number; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage }
+  /**
+   * The model requested one tool invocation: `name` with the raw `arguments`
+   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
+   * call with its `tool/result`.
+   */
   'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
+  /**
+   * A completed tool call's model-facing result, plus an optional tool-private
+   * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the
+   * producing tool owns its shape and reads it back in `presentResult`) but MUST
+   * be JSON-serializable: `Session.append` runtime-validates all event data with
+   * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the
+   * durable log reproduces the identical card on replay. Absent unless the tool
+   * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
+   */
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
-  /**
-   * The agent's whole todo list, carried as a full snapshot and replaced
-   * wholesale on each write — the current list is the most recent `todo/write`
-   * (last-write-wins on replay, no fold). Appended by an owning agent via
-   * `session.append('todo/write', { todos })`.
-   *
-   * NOT a {@link SurfaceEventType}: it produces no LLM message and never reaches
-   * `deriveMessages()`, so it carries no `surfaceOp` and stays off the surface —
-   * it is durable, replayable UI state, distinct from the conversation history.
-   * It is a `SessionEventMap` member riding the existing `session/event` emit,
-   * not a first-class Cordis `interface Events` notification, so it has no
-   * cordis-catalog row.
-   */
+  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
   'todo/write': { todos: TodoItem[] }
   /**
-   * Full snapshot of the {@link EpochHeader} the NEXT request is built under,
-   * with the {@link RequestHeaderReason} it was recorded whole. Appended by
-   * the loop inside the step, before dispatch, on a loop instance's first
-   * request-building step (`'initial'`/`'resume'`) or when a later request's
-   * header changes (`'change'`); always records what the request actually
-   * used, post-`agent/request`. Reconstruction reads the latest snapshot. NOT a
-   * {@link SurfaceEventType}: it produces no LLM message — it is the request
-   * envelope, logged so every request is a pure function of the session log
-   * (the reconstructability RFC).
+   * Full header for the next request, appended inside its step before dispatch.
+   * It is log-only; the latest snapshot reconstructs the request header.
    */
   'request/header': { header: EpochHeader; reason: RequestHeaderReason }
 }
@@ -95,8 +104,21 @@ interface SessionEventMap {
 The unit of the `todo/write` event's whole-list snapshot. Deliberately minimal — a `content` line and a three-state `status` (no id, priority, or `activeForm`): the list is replaced wholesale on every write, so entries need no stable identity, and the status triple is exactly the ACP `PlanEntryStatus`, so a UI bridge can map a todo list onto an ACP `plan` 1:1 (synthesizing the priority ACP additionally requires). See the [todo_write RFC](../rfc/implemented/feature/2026-06-29-todo-write-tool.md).
 
 ```ts type-equiv
-export interface TodoItem {
+/**
+ * One entry in an agent's todo list — the unit of the `todo/write`
+ * {@link SessionEventMap} event's whole-list snapshot.
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity, and the
+ * status triple is exactly the ACP `PlanEntryStatus`, so a UI bridge can map a
+ * todo list onto an ACP `plan` 1:1 (synthesizing the priority ACP additionally
+ * requires).
+ */
+interface TodoItem {
+  /** What this task is — a short imperative line shown in the UI. */
   content: string
+  /** Lifecycle state. `in_progress` marks the single task being worked now. */
   status: 'pending' | 'in_progress' | 'completed'
 }
 ```
@@ -106,8 +128,13 @@ export interface TodoItem {
 The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + the session prefix) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
 
 ```ts type-equiv
-export interface EpochHeader {
-  /** The conversation's call configuration (provider + model + sampling scalars). */
+/**
+ * Logged request state outside derived history: call config, system prompt,
+ * tools, and prefix. The latest full `request/header` snapshot reconstructs it;
+ * canonical empty optional fields are absent.
+ */
+interface EpochHeader {
+  /** The conversation's call configuration (provider, model, and sampling scalars). */
   config: LlmCallConfig
   /** Rendered system prompt text; absent for a system-less request. */
   system?: string
@@ -131,6 +158,19 @@ Canonical form: an empty system prompt, an empty tool list, and an empty session
 A proper discriminated union over `type` (not independent `type`/`data` unions), so `switch (event.type)` narrows `event.data` without casts. `seq` is the monotonic position in the log (`seq = log.length`); `time` is epoch ms.
 
 ```ts type-equiv
+/**
+ * One immutable entry in the session log.
+ *
+ * A proper discriminated union over `type` (not independent `type`/`data`
+ * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
+ */
 type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
     type: K
@@ -143,7 +183,9 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /**
      * Seq numbers of events that are provenance sources of this event
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node).
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -163,7 +205,12 @@ The five message-producing types (`SurfaceEventType` — `user/message`, `assist
 ### `SurfaceEventType` — the message-producing subset of event types
 
 ```ts type-equiv
-export type SurfaceEventType =
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the ordered surface. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+type SurfaceEventType =
   | 'user/message'
   | 'assistant/message'
   | 'tool/result'
@@ -174,7 +221,19 @@ export type SurfaceEventType =
 ### `SurfaceOp` — how an event entered the surface
 
 ```ts type-equiv
-export type SurfaceOp =
+/**
+ * How a session event entered the ordered surface. Only valid on
+ * {@link SurfaceEventType} events.
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+type SurfaceOp =
   | 'append'
   | { op: 'replace'; start: number; end: number }
 ```
@@ -184,8 +243,18 @@ export type SurfaceOp =
 ### `SurfaceIntent` — the parameter to `session.append()`
 
 ```ts type-equiv
-export interface SurfaceIntent {
+/**
+ * Surface placement and provenance for {@link Session.append}. Required on
+ * message-producing events and forbidden on log-only events.
+ */
+interface SurfaceIntent {
   surfaceOp: SurfaceOp
+  /**
+   * Complete known provenance source set. `assistant/message` may use a
+   * present empty array for a known empty provider stream; omission means its
+   * provenance was not recorded. Other surface events require a non-empty set
+   * when this field is present.
+   */
   sourceEventSeqs?: number[]
 }
 ```
@@ -194,22 +263,44 @@ Required for `SurfaceEventType` events — every message-producing event must de
 
 The same provenance distinction applies here: only `assistant/message` may carry a present empty `sourceEventSeqs`; omission does not assert that its source stream was empty.
 
-### `SurfaceFoldReplacement` and `SurfaceFoldResult` — a complete surface replay
+### `SessionSurface` — the live readonly surface projection
 
-`foldSurface(events)` returns detached current event sequences together with the actual sequences shadowed by each declared replacement range. `SurfaceManager` uses the same transitions for its incremental cache without retaining replacement history. Its `replaceGeneration` increments for each replacement so incremental consumers can distinguish pure tail growth from a rewrite.
+`Session.surface` returns the session's stable `SessionSurface` view. The same incremental manager validates append candidates before commit and advances this projection from committed events; callers can observe membership and replacement generation but cannot invoke validation.
 
 ```ts type-equiv
-export interface SurfaceFoldReplacement {
+/** Readonly live projection of the message-producing session events. */
+interface SessionSurface {
+  /** Current surface event sequences in model-visible order. */
+  readonly nodes: readonly number[]
+  /** Monotonic count of committed positional replacements. */
+  readonly replaceGeneration: number
+}
+```
+
+### `SurfaceFoldReplacement` and `SurfaceFoldResult` — a complete surface replay
+
+`foldSurface(events)` returns detached current event sequences together with the actual sequences shadowed by each declared replacement range. The live manager uses the same transitions without retaining replacement history. Its `replaceGeneration` increments for each committed replacement so incremental consumers can distinguish pure tail growth from a rewrite.
+
+```ts type-equiv
+/** One replacement operation observed while folding a session surface. */
+interface SurfaceFoldReplacement {
+  /** Seq of the event that replaced the prior surface range. */
   seq: number
+  /** Declared inclusive start seq of the replaced surface range. */
   start: number
+  /** Declared inclusive end seq of the replaced surface range. */
   end: number
+  /** Actual surface entries removed by the operation, in surface order. */
   shadowedSeqs: number[]
 }
 ```
 
 ```ts type-equiv
-export interface SurfaceFoldResult {
+/** Complete result of replaying the surface operations in a session log. */
+interface SurfaceFoldResult {
+  /** Current surface event sequences in model-visible order. */
   nodes: number[]
+  /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
 ```
@@ -237,6 +328,10 @@ An explicit `boundary` lets callers fork from a previous completed turn even if
 ## What started a turn: `TurnTriggerMap`
 
 ```ts type-equiv
+/**
+ * What started a turn.
+ * Merge-extensible sum type (same pattern as MessageSourceMap).
+ */
 interface TurnTriggerMap {
   message: { kind: 'message'; source: MessageSource }
   /**
@@ -254,6 +349,9 @@ interface TurnTriggerMap {
 ## Why a turn ended: `TurnEndReasonMap`
 
 ```ts type-equiv
+/**
+ * Why a turn ended. Merge-extensible sum type.
+ */
 interface TurnEndReasonMap {
   completed: { kind: 'completed' }
   aborted: { kind: 'aborted'; reason?: string }
@@ -265,26 +363,16 @@ interface TurnEndReasonMap {
    */
   error: { kind: 'error'; step: number; message: string; code?: string }
   disposed: { kind: 'disposed' }
+  /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
   'max-tokens': { kind: 'max-tokens' }
   /**
-   * The turn's entire prompt batch was BLOCKED before any step ran — every
-   * drained queued message was vetoed by an `agent/prompt-submit` listener (a
-   * hook). The turn still opened (so the boundary stays balanced and the block
-   * is a durable in-turn fact), but ran zero steps. `reason` carries the block
-   * message from the vetoing decision. Distinct from `aborted` (a user-driven
-   * cancel) and `error` (a failure): the prompt was rejected by policy, not
-   * interrupted or broken. A UI renders it as "prompt blocked by hook".
+   * Policy blocked every prompt before the first step. The zero-step turn still
+   * records a balanced durable boundary and the veto reason.
    */
   rejected: { kind: 'rejected'; reason: string }
   /**
-   * The turn never ended on its own: the process crashed mid-turn and a
-   * persistence backend later closed the orphaned (open) turn on reload so the
-   * log stays balanced. SYNTHESIZED by the backend's crash-recovery repair — no
-   * loop ever emits this. Its events are real (they were durably appended before
-   * the crash) and are PRESERVED, not discarded: a single turn can be huge in a
-   * long-horizon task (many steps, large tool output), so truncating it would
-   * lose real work. The marker records that the turn was cut short, not that the
-   * model completed it. See the session-persistence RFC.
+   * A persistence backend closed a crash-orphaned turn on reload. The loop never
+   * emits this marker, and the events recorded before the crash remain intact.
    */
   interrupted: { kind: 'interrupted' }
 }
diff --git a/docs/core-data-structures/skills.md b/docs/core-data-structures/skills.md
index 93189ba2cb..daccb38550 100644
--- a/docs/core-data-structures/skills.md
+++ b/docs/core-data-structures/skills.md
@@ -11,9 +11,25 @@ Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/ind
 Duplicate names resolve by rank, provider order, then local order; summaries sort by name. A rejected `list()` is logged and skipped without caching the degraded catalog, while malformed candidates fail fast.
 
 ```ts type-equiv
+/** Provider interface for one source of skills, such as local directories or a remote registry. */
 interface SkillProvider {
+  /** Unique provider name in the `ctx.skills` registry. */
   readonly name: string
+  /**
+   * List available skill candidates for the current lookup context. Provider
+   * plugins register synchronously during `apply()`; remote initialization,
+   * authentication, and discovery are awaited inside this method. Implementations
+   * should settle promptly when `options.signal` aborts.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns provider candidates with precedence ranks and opaque locators.
+   */
   readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>
+  /**
+   * Load a complete skill body for a previously listed candidate.
+   * @param candidate - the winning candidate originally returned by this provider.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns the full skill body, or `undefined` if it is no longer loadable.
+   */
   readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
 }
 ```
@@ -37,6 +53,7 @@ The project root is the nearest ancestor containing `.git`; without one, the cur
 Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1.
 
 ```ts type-equiv
+/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
 type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {})
 ```
 
@@ -45,13 +62,21 @@ type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | '
 `SkillSummary` is the registry's model-invocable summary shape. Consumers choose which fields to render; the session catalog uses only `name` and `description`, never the body or absolute file path. `disableModelInvocation` hides a skill from model listings while allowing trusted code to load it by name.
 
 ```ts type-equiv
+/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
 interface SkillSummary {
+  /** Kebab-case identifier used with the `skill` tool. */
   readonly name: string
+  /** Short routing description shown to the model. */
   readonly description: string
+  /** Optional extra routing guidance shown to the model. */
   readonly whenToUse?: string
+  /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
   readonly disableModelInvocation?: boolean
+  /** Discovery source that produced this winning skill. */
   readonly source: SkillSource
+  /** Provider that owns this skill body. */
   readonly provider: string
+  /** Provider-specific base for relative resources. */
   readonly resourceBase?: SkillResourceBase
 }
 ```
@@ -59,10 +84,15 @@ interface SkillSummary {
 `SkillCandidate` is the provider-to-registry shape. `locator` is opaque provider state; the registry only stores it and gives it back to the winning provider's `get()`.
 
 ```ts type-equiv
+/** Provider catalog entry used by the registry to merge and later load skills. */
 interface SkillCandidate extends SkillSummary {
+  /** Lower ranks win duplicate skill names before provider registration order is considered. */
   readonly rank: number
+  /** Opaque provider-owned handle passed back to `provider.get()`. */
   readonly locator: unknown
+  /** Absolute file path when the provider has one. */
   readonly path?: string
+  /** Parsed optional metadata object from provider-specific skill frontmatter. */
   readonly metadata?: Readonly<Record<string, unknown>>
 }
 ```
@@ -70,6 +100,7 @@ interface SkillCandidate extends SkillSummary {
 `SkillDefinition` is the complete parsed result returned by `ctx.skills.get()` and used by the `skill` tool. `resourceBase` tells the tool how to render relative-resource guidance for local, URL, or provider-managed skills.
 
 ```ts type-equiv
+/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
 type SkillResourceBase =
   | { readonly kind: 'directory'; readonly path: string }
   | { readonly kind: 'url'; readonly url: string }
@@ -77,9 +108,13 @@ type SkillResourceBase =
 ```
 
 ```ts type-equiv
+/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
 interface SkillDefinition extends SkillSummary {
+  /** Markdown instruction body after any provider-specific metadata removal. */
   readonly content: string
+  /** Absolute file path when the skill came from disk. */
   readonly path?: string
+  /** Parsed optional metadata object from frontmatter. */
   readonly metadata?: Readonly<Record<string, unknown>>
 }
 ```
@@ -87,9 +122,8 @@ interface SkillDefinition extends SkillSummary {
 Runtime skills use the same complete shape and participate in the same first-wins collection order. The returned disposer removes the contribution and invalidates discovery caches.
 
 ```ts type-equiv
-type SkillRegistration = Omit<SkillDefinition, 'provider'> & {
-  readonly provider?: string
-}
+/** Runtime skill contribution accepted by `ctx.skills.register()`. */
+type SkillRegistration = Omit<SkillDefinition, 'provider'> & { readonly provider?: string }
 ```
 
 ## Lookup and configuration
@@ -97,8 +131,11 @@ type SkillRegistration = Omit<SkillDefinition, 'provider'> & {
 Skill lookup is cwd-sensitive because providers may expose workspace-local skills, and its optional signal cancels provider work for the caller. Providers receive the same readonly options object used for cache identity and loading. Cancellation is checked before and after catalog selection, including cache hits, and races both discovery and full-definition loading. If no git root is found, the local provider treats the supplied cwd itself as the project root.
 
 ```ts type-equiv
+/** Caller context used for cwd-sensitive and abortable provider work. */
 interface SkillLookupOptions {
+  /** Workspace selector for the current lookup. */
   readonly cwd?: string | undefined
+  /** Abort discovery or loading work for the current caller. */
   readonly signal?: AbortSignal | undefined
 }
 ```
@@ -106,7 +143,9 @@ interface SkillLookupOptions {
 The registry owns only its discovery-cache bound. The local provider owns filesystem roots (`dshHome`, `agentsHome`, and `customSkillDirs`). The consumer owns its catalog description bound.
 
 ```ts type-equiv
+/** Skill registry configuration. */
 interface Config {
+  /** Maximum number of completed cwd/provider catalogs kept in memory. */
   readonly collectCacheMaxEntries?: number
 }
 ```
diff --git a/docs/core-data-structures/spill.md b/docs/core-data-structures/spill.md
index 4e8ced8258..d046874b0e 100644
--- a/docs/core-data-structures/spill.md
+++ b/docs/core-data-structures/spill.md
@@ -9,15 +9,28 @@ Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/typ
 `saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), WHERE it came from (`source`, descriptive provenance for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
 
 ```ts type-equiv
+/** One request to persist text to a spill artifact. */
 interface SaveTextSpill {
   owner: SpillOwner
   source: SpillSource
+  /**
+   * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
+   * it to a single safe path segment before use — it is a hint, never a path.
+   */
   suggestedName: string
+  /** The full text to persist (UTF-8). */
   content: string
 }
 ```
 
 ```ts type-equiv
+/**
+ * Save-time storage namespace for a spilled artifact. The session id lets a
+ * backend group storage under the producing session, but the returned
+ * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
+ * locators already present in the seeded log; those artifacts are not copied or
+ * re-owned, and spills produced after the fork use the child session id.
+ */
 interface SpillOwner {
   sessionId: SessionId
 }
@@ -26,9 +39,17 @@ interface SpillOwner {
 `SpillOwner.sessionId` is the save-time storage namespace. Forked sessions inherit existing spill locators from the seeded log; those artifacts are not copied or re-owned, and spills produced after the fork use the child session id. A retention-period cleanup may expire old locators with other old session artifacts; the spill seam does not define a per-session cleanup policy.
 
 ```ts type-equiv
+/**
+ * Provenance of one spilled artifact — recorded by the backend for a readable
+ * filename and inspection. Not interpreted for access control; purely
+ * descriptive.
+ */
 interface SpillSource {
+  /** The tool whose result was spilled (e.g. `web_fetch`). */
   toolName: string
+  /** The model-issued call id the result belongs to. */
   callId: CallId
+  /** A short human label for the artifact (e.g. `result`). */
   label: string
 }
 ```
@@ -36,6 +57,7 @@ interface SpillSource {
 ## The result
 
 ```ts type-equiv
+/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
 interface SpillRef {
   locator: SpillLocator
   bytes: number
@@ -46,6 +68,11 @@ interface SpillRef {
 `SpillLocator` is a [branded](core.md#branded-ids) model-facing handle returned by the backend. The local backend renders it as a filesystem path; a remote or database backend can render a URI, key, or command token. Consumers treat it as opaque and render it with `retrievalHint` instead of assuming `read` is always the right retrieval mechanism.
 
 ```ts type-equiv
+/**
+ * Opaque model-facing handle for one spilled artifact. A local backend may use a
+ * filesystem path; a remote or database backend may use a URI or key. Consumers
+ * render it with {@link SpillRef.retrievalHint}, but do not parse it.
+ */
 type SpillLocator = Branded<'SpillLocator'>
 ```
 
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 815438f215..d279f26a9d 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -11,10 +11,22 @@ Source: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/suba
 A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. **Runtime** features (steering, resume) are instead optional methods on [`SubagentRun`](#a-live-run-subagentrun) — the method's presence IS the capability, and TS narrowing is the discovery mechanism.
 
 ```ts type-equiv
+/**
+ * Which START-TIME features a provider supports. Checked by the service before delegating to
+ * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
+ * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
+ * degradation" rule). These static flags cover features needed before a run exists; runtime
+ * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence
+ * is the capability.
+ */
 interface SubagentCapabilities {
+  /** Honor {@link SubagentStartRequest.outputSchema} (structured final output). */
   readonly outputSchema: boolean
+  /** Enforce {@link SubagentStartRequest.maxDepth} (recursion cap). */
   readonly depthLimit: boolean
+  /** Enforce {@link SubagentStartRequest.toolFilter} (child tool scoping). */
   readonly toolFilter: boolean
+  /** Honor {@link SubagentStartRequest.persona} (a per-child persona). */
   readonly persona: boolean
 }
 ```
@@ -24,14 +36,60 @@ interface SubagentCapabilities {
 The tool layer builds this request from the model input and its own config; the service validates it against the named provider before `start`. Required `parent` supplies the session cwd, lineage, and delegation depth. Optional output schema, depth, tool filter, and persona require matching capability flags. Unsupported schemas fail at start; in-process backends scope filters and personas to child creation and implement the supported object-rooted schema with a forced capture tool.
 
 ```ts type-equiv
+/**
+ * What a caller asks for when starting a subagent. The tool layer builds this
+ * from the model's `{ description, prompt }` plus its own config; the service
+ * validates {@link SubagentCapabilities} against the named provider, then
+ * passes it to {@link SubagentProvider.start}.
+ */
 interface SubagentStartRequest {
+  /** The task/prompt for the child agent (a user message in the child session). */
   readonly prompt: ContentBlock[]
+  /**
+   * The spawning ("parent") agent — the one whose tool call started this
+   * subagent. REQUIRED: in-process backends read `parent.session.header` for
+   * the working directory, the `parentSession` lineage to stamp on the child,
+   * and the parent's delegation depth. Out-of-process backends (ACP) ignore it.
+   */
   readonly parent: Agent
+  /**
+   * Cancellation signal from the spawning context (the tool's `exec.signal`).
+   * This is the canonical cancellation channel both before and after startup:
+   * a provider rejects `start()` after cleaning partial resources when it
+   * fires before publication, and cancels a published child when it fires
+   * afterward.
+   */
   readonly signal: AbortSignal
+  /** Per-child agent options (model and plugin-defined extension fields). */
   readonly agentOptions?: AgentOptions
+  /**
+   * Object-rooted JSON Schema within `assertSupportedOutputSchema`'s enforced subset. Start rejects
+   * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
+   * a successful child returns the matching value as {@link SubagentResult.structured}.
+   */
   readonly outputSchema?: StructuredOutputSchema
+  /**
+   * Optional absolute delegation-depth cap for the child being started: its
+   * computed depth must be less than or equal to this non-negative safe
+   * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
+   * start otherwise.
+   */
   readonly maxDepth?: number
+  /**
+   * Optional child tool scoping. Requires {@link SubagentCapabilities.toolFilter};
+   * rejected at start otherwise. In-process backends apply it as a scoped
+   * `tools.restrict()` in the child's creation window: the named tools vanish
+   * from the child's prompt AND refuse to execute (one visibility), with loud
+   * unknown-name validation.
+   */
   readonly toolFilter?: ToolRestriction
+  /**
+   * Optional per-child persona. Requires {@link SubagentCapabilities.persona};
+   * rejected at start otherwise. In-process backends register it as a scoped
+   * `deployment:persona` section on the child, SHADOWING the deployment's
+   * persona for this child alone — same template semantics as the deployment
+   * persona (strict `{{…}}` interpolation against the registered variables).
+   */
   readonly persona?: string
 }
 ```
@@ -43,9 +101,21 @@ interface SubagentStartRequest {
 The outcome of a run, resolved by `SubagentRun.result`. `structured` is present only after a requested `outputSchema` was successfully satisfied; requesting a schema does not guarantee it, and a provider may return `stopReason: 'error'` when the child fails or finishes without a valid capture. A non-`completed` `stopReason` means `output` may be partial — the consumer maps it to an `isError` tool result rather than reporting partial output as success.
 
 ```ts type-equiv
+/**
+ * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
+ */
 interface SubagentResult {
+  /** The child's final assistant output (the last assistant message's content). */
   readonly output: ContentBlock[]
+  /**
+   * The structured result after a requested `outputSchema` was successfully
+   * satisfied. Requesting a schema does not guarantee presence: a provider can
+   * end with `stopReason: 'error'` when the child fails or finishes without a
+   * valid capture. Shape is validated against the request schema by the
+   * provider; `unknown` here because the seam is schema-agnostic.
+   */
   readonly structured?: unknown
+  /** Why the run ended. A non-`completed` reason means `output` may be partial. */
   readonly stopReason: SubagentStopReason
 }
 ```
@@ -53,11 +123,22 @@ interface SubagentResult {
 `SubagentStopReason` is a [merge-extensible derived union](core.md#the-map--derived-union-pattern) — a backend may add variants, so consumers branch on the known cases and treat an unknown terminal reason as a failure:
 
 ```ts type-equiv
+/**
+ * Why a subagent run ended. Merge-extensible (a backend may add variants);
+ * consumers branch on the known cases and fall through `default`. The known
+ * cases mirror the harness turn-end vocabulary so the tool layer can map a
+ * non-`completed` result to an `isError` tool result.
+ */
 interface SubagentStopReasonMap {
+  /** The child finished its turn normally. */
   completed: 'completed'
+  /** The run was cancelled by its request signal or by disposal. */
   aborted: 'aborted'
+  /** The child failed (model error, transport error). */
   error: 'error'
+  /** The child hit its token ceiling before finishing. */
   'max-tokens': 'max-tokens'
+  /** The child declined the task. */
   refusal: 'refusal'
 }
 ```
@@ -67,12 +148,47 @@ interface SubagentStopReasonMap {
 `SubagentRun` is the consumer-owned handle for a ready child. Consumers await `result` and always dispose the run to reach quiescence. Child failures resolve with a non-completed stop reason; only unrepresentable infrastructure faults reject. Optional `sendMessage` and `resume` methods advertise their runtime capabilities by presence.
 
 ```ts type-equiv
+/**
+ * Child handle returned only after readiness. Consumers await {@link result} and must always
+ * {@link dispose} to cancel remaining work and reach quiescence. Optional methods are runtime
+ * capability discovery; narrow their presence before calling.
+ */
 interface SubagentRun {
+  /**
+   * Parent-scoped run id. For a local run, this MUST equal the published child
+   * session id, whose `parentSession` records `request.parent.session.id`; a
+   * remote provider mints an id unique in the parent namespace.
+   */
   readonly id: SessionId
+  /**
+   * The exact published in-process child, or `undefined` for a remote run.
+   * When present, its id is {@link id}; the provider retains no ownership
+   * implication beyond the run's ordinary {@link dispose} contract.
+   */
   readonly localAgent: Agent | undefined
+  /**
+   * Resolves with the child's terminal {@link SubagentResult} when the run
+   * settles. Does NOT reject on a child-level failure — a model/transport
+   * failure resolves with `stopReason: 'error'` so the consumer maps it to an
+   * `isError` tool result. Rejects only on an infrastructure fault the seam
+   * cannot represent as a stop reason.
+   */
   readonly result: Promise<SubagentResult>
+  /**
+   * Cancel remaining work, reach child quiescence, and release the run's
+   * resources (in-process: dispose the owned agent and remove its session;
+   * ACP: kill and reap the subprocess). Idempotent.
+   */
   dispose(): Promise<void>
+  /**
+   * OPTIONAL (steering capability): send additional content to the running
+   * child between steps. Present only on providers that support live steering.
+   */
   sendMessage?(content: ContentBlock[]): void
+  /**
+   * OPTIONAL (resume capability): send a follow-up task to a settled child,
+   * continuing its session, and return a fresh run for the continuation.
+   */
   resume?(content: ContentBlock[]): Promise<SubagentRun>
 }
 ```
@@ -84,10 +200,33 @@ A local run MUST publish an ordinary child agent/session before `start()` fulfil
 Each provider is a named child-agent transport, and multiple providers may coexist. The service validates requested start-time capabilities before `start()`. `inheritsParentContext` describes only conversation seeding (`fork`: true; `spawn` and `acp`: false), allowing consumers to generate accurate model-facing wording without implying inherited tools, services, or authority.
 
 ```ts type-equiv
+/**
+ * A subagent backend: one transport for running a child agent (in-process
+ * spawn/fork, ACP to another process, …). Implementations register under a
+ * unique name via {@link SubagentService.registerProvider}; multiple providers
+ * coexist in one context (unlike the single-implementation bash seam). The
+ * Providers are trusted same-process implementations; callers treat their
+ * descriptors and returned values as borrowed immutable data.
+ */
 interface SubagentProvider {
+  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
   readonly name: string
+  /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
   readonly capabilities: SubagentCapabilities
+  /**
+   * Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
+   * service-validated start capability: the model-facing tool derives truthful wording from it.
+   * It says nothing about tool registration, injected services, or authority inheritance.
+   */
   readonly inheritsParentContext: boolean
+  /**
+   * Establish a child and return its handle only after publication. The
+   * service has already validated that every requested start-time capability
+   * is supported, so an implementation may assume e.g. `request.maxDepth` is
+   * honorable when present. If setup fails or `request.signal` aborts before
+   * fulfillment, the provider owns and cleans all partial resources before this
+   * promise rejects. Ownership transfers to the caller only on fulfillment.
+   */
   start(request: SubagentStartRequest): Promise<SubagentRun>
 }
 ```
diff --git a/docs/core-data-structures/system-prompt.md b/docs/core-data-structures/system-prompt.md
index 4b6f1e6625..04c86aabe6 100644
--- a/docs/core-data-structures/system-prompt.md
+++ b/docs/core-data-structures/system-prompt.md
@@ -9,7 +9,12 @@ Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-
 `AssembleContext` identifies the scope layer one assembly resolves. It is merge-extensible: `dsh-agent` adds the optional live `agent` field, and `assembleContextFor(agent)` sets that field and `scope` together.
 
 ```ts type-equiv
+/** Merge-extensible context for one prompt assembly. */
 interface AssembleContext {
+  /**
+   * Scope whose providers and waterfall listeners participate. When absent,
+   * only global providers and subject-less listeners participate.
+   */
   scope?: ScopeKey
 }
 ```
@@ -19,8 +24,11 @@ interface AssembleContext {
 `ToolProviderResult.schemas` is the model-visible set for the current assembly. `knownNames` is the provider's pre-restriction name universe used to distinguish a configured-name typo from a known tool that is deliberately hidden in this scope.
 
 ```ts type-equiv
+/** Tool schemas visible in one assembly and their pre-restriction name set. */
 interface ToolProviderResult {
+  /** The schemas this provider contributes to THIS assembly. */
   readonly schemas: readonly ToolSchema[]
+  /** The pre-restriction name universe for config validation (defaults to `schemas`' names). */
   readonly knownNames?: readonly string[]
 }
 ```
@@ -30,9 +38,21 @@ interface ToolProviderResult {
 `PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context.
 
 ```ts type-equiv
+/** One contributed section of the system prompt (registry input). */
 interface PromptSection {
+  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.section}). */
   readonly name: string
+  /**
+   * Sections are concatenated in ascending order. Convention: `-100` is the
+   * harness identity, `0` the deployment persona, tool guidance uses 100–199;
+   * other negative orders also render before the persona.
+   */
   readonly order: number
+  /**
+   * Static text or a provider evaluated at each assembly with that assembly's
+   * {@link AssembleContext}. The text may reference `{{variable}}`s — they are
+   * interpolated later, by {@link renderPrompt}.
+   */
   readonly text: string | ((context: AssembleContext) => string)
 }
 ```
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 0482912af7..ebe2062a84 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -7,6 +7,10 @@ Types shared by long-running producers, `ctx.tasks`, and task control surfaces.
 `TaskId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `TaskKind` derives from a merge-extensible map; the registry treats kinds as opaque id namespaces.
 
 ```ts type-equiv
+/**
+ * Producer-defined task kinds. Plugins extend this map by declaration merging;
+ * the registry treats every value as an opaque id namespace.
+ */
 interface TaskKindMap {
   bash: 'bash'
   subagent: 'subagent'
@@ -20,6 +24,11 @@ interface TaskKindMap {
 `TaskStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.
 
 ```ts type-equiv
+/**
+ * Producer declaration passed to {@link TaskService.start}. The runtime
+ * preflights access and cleanup before invoking {@link run}; the producer owns
+ * execution resources while the runtime owns identity and lifecycle state.
+ */
 interface TaskStart {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
   kind: TaskKind
@@ -44,6 +53,7 @@ interface TaskStart {
 `TaskHooks.done` is the quiescence boundary. Optional `readOutput` distinguishes consuming stream tasks from final-output-only tasks.
 
 ```ts type-equiv
+/** Hooks through which the runtime controls and observes producer work. */
 interface TaskHooks {
   /**
    * Request termination. Must be synchronous, idempotent, and eventually settle
@@ -67,6 +77,7 @@ interface TaskHooks {
 ```
 
 ```ts type-equiv
+/** Terminal result supplied by a producer through {@link TaskHooks.done}. */
 interface TaskOutcome {
   /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
@@ -82,6 +93,10 @@ interface TaskOutcome {
 Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another surface has delivered or committed to deliver the terminal state.
 
 ```ts type-equiv
+/**
+ * A read-only projection of one task, safe to hand to listeners and tools —
+ * a fresh object per call, never live registry state.
+ */
 interface TaskSnapshot {
   /** The registry-issued id (`<kind>-N`). */
   id: TaskId
@@ -112,6 +127,7 @@ interface TaskSnapshot {
 ```
 
 ```ts type-equiv
+/** Output and post-read state returned by {@link TaskService.read}. */
 interface TaskRead {
   /**
    * Stream kinds: the consuming delta since the previous read. Final-output
diff --git a/docs/core-data-structures/token-meter.md b/docs/core-data-structures/token-meter.md
index e082ea08a9..880ec79d7d 100644
--- a/docs/core-data-structures/token-meter.md
+++ b/docs/core-data-structures/token-meter.md
@@ -7,6 +7,7 @@ Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter
 ## `TokenMeasurement`
 
 ```ts type-equiv
+/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
 interface TokenMeasurement {
   /** Number of durable events consumed; equal to the next unread event seq. */
   readonly logRevision: number
@@ -28,6 +29,7 @@ interface TokenMeasurement {
 ## `TokenSurfaceNode`
 
 ```ts type-equiv
+/** One token-priced node in the current ordered session surface. */
 interface TokenSurfaceNode {
   /** Durable sequence number of the surface event. */
   readonly seq: number
diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index edb20586bc..7cc0910d90 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -9,6 +9,7 @@ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index
 A `ToolSchema` (the model-facing fields) plus the `execute` function, host-only scheduler metadata, and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist — `execute`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` must never leak into a model request.
 
 ```ts type-equiv
+/** A registered tool: its schema plus the execution function. */
 interface ToolDefinition extends ToolSchema {
   execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>
   /**
@@ -26,7 +27,9 @@ interface ToolDefinition extends ToolSchema {
    *
    * Opted-in executions must not mutate parent-owned state. Shared state must
    * tolerate concurrent dispatch; recorder races are permitted only when they
-   * commute or fail closed. See the parallel-tool-call RFC for the full contract.
+   * commute or fail closed. See the
+   * [parallel-tool-call RFC](../../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
+   * for the full contract.
    * @param args - parsed arguments; `defineTool` validates before calling.
    * @returns Whether this call may join a parallel group.
    */
@@ -61,6 +64,7 @@ Plugin authors write per-property specs with a boolean `required: true`, and a t
 Source: [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
 
 ```ts type-equiv
+/** One schema-spec property entry. */
 interface SchemaProp {
   type: SchemaType
   /** Per-property required flag (NOT the JSON Schema top-level required array). */
@@ -69,7 +73,10 @@ interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
-  /** Default value. */
+  /**
+   * Model-visible JSON Schema default annotation. Validation does not apply it;
+   * dynamic tool mounts may supply it even though first-party definitions do not.
+   */
   default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec
@@ -79,12 +86,29 @@ interface SchemaProp {
 ```
 
 ```ts type-equiv
+/**
+ * The author-facing parameter schema: a shallow map of property name to
+ * {@link SchemaProp}. Required-ness is a per-property boolean (`required:
+ * true`), not a separate array.
+ */
 type SchemaSpec = Record<string, SchemaProp>
 ```
 
 `SchemaType` is the primitive union `'string' | 'number' | 'boolean' | 'object' | 'array'`. `InferArgs<S>` maps a `SchemaSpec` to the TS argument type — `required: true` props become required keys, everything else genuinely optional:
 
 ```ts type-equiv
+/**
+ * Infer the TS argument type for a complete {@link SchemaSpec}.
+ *
+ * Properties marked `required: true` are required keys; all others are
+ * genuinely optional keys (`?`), so callers may omit them entirely.
+ *
+ * Example:
+ * ```ts
+ * type Args = InferArgs<{ path: { type: 'string'; required: true }; limit: { type: 'number' } }>
+ * // → { path: string; limit?: number }
+ * ```
+ */
 type InferArgs<S extends SchemaSpec> = Simplify<
   & { [K in RequiredKeys<S>]: InferPropValue<S[K]> }
   & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferPropValue<S[K]> }
@@ -100,8 +124,14 @@ Registration is a trusted same-process contract. The registry borrows the typed
 `ToolRestriction` applies only to the live deployment-global tool layer. The registry compiles readonly names into private sets, intersects multiple restrictions, then overlays scope-local tools. A deny-only filter admits later unlisted globals, while an allow-list excludes them.
 
 ```ts type-equiv
+/**
+ * Per-scope filter over global tools. Restrictions intersect and do not affect
+ * scoped registrations or the reserved Code Mode transport.
+ */
 interface ToolRestriction {
+  /** Global tool names that stay visible; everything else is removed. */
   readonly allow?: readonly string[]
+  /** Global tool names removed from visibility. */
   readonly deny?: readonly string[]
 }
 ```
@@ -111,14 +141,20 @@ interface ToolRestriction {
 `ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace the result) → `tools/result` (the immutable authoritative outcome). The outcome is a `ToolExecutionResult`.
 
 ```ts type-equiv
+/** Opaque call identity that permits correlation without exposing mutable execution state. */
 type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
 ```
 
 ```ts type-equiv
+/**
+ * Caller-supplied description of one tool call. {@link ToolRegistry.execute}
+ * adds the registry-owned token to form a pipeline {@link ToolExecution};
+ * callers do not choose that token.
+ */
 interface ToolExecutionInput {
   readonly callId: CallId
   readonly name: string
-  /** Parsed JSON arguments (unknown — tools validate their own input). */
+  /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
   /** The agent on whose behalf the call runs (set by the agent loop). */
   readonly agent?: Agent
@@ -135,6 +171,12 @@ interface ToolExecutionInput {
 A tool body receives the runtime extension. `deferContext()` is the composite-tool channel: it records nested-dispatch context without injecting inside the still-open outer call.
 
 ```ts type-equiv
+/**
+ * Runtime context handed to a tool implementation after the registry has
+ * accepted a {@link ToolExecution}. A composite tool uses
+ * {@link deferContext} to ferry context produced by nested dispatches back to
+ * the outer result; the loop appends it only after the outer `tool/result`.
+ */
 interface ToolRunContext extends ToolExecution {
   /**
    * Defer one nested-dispatch context until this tool's final result reaches
@@ -148,12 +190,23 @@ interface ToolRunContext extends ToolExecution {
 The agent loop asks the registry for each pending call's execution mode and uses it to form exclusive barriers and rolling-pool parallel runs:
 
 ```ts type-equiv
+/**
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
+ * `exclusive` runs alone and forms an ordering barrier.
+ */
 type ToolExecutionMode =
   | { kind: 'parallel' }
   | { kind: 'exclusive' }
 ```
 
 ```ts type-equiv
+/**
+ * One pending tool call inside the registry pipeline. Parsed arguments cross
+ * one lossless-JSON materialization boundary before policy and are deep-frozen;
+ * call identity and the registry-assigned {@link token} are readonly. An
+ * around-dispatch wrapper may set, replace, or remove `signal`. The registry
+ * freezes the complete object before `tools/result` observers run.
+ */
 interface ToolExecution extends ToolExecutionInput {
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
@@ -165,10 +218,19 @@ interface ToolExecution extends ToolExecutionInput {
 A `ToolGuard` is scope-aware final pre-dispatch policy. Its shape deliberately has no allow result: `undefined` preserves the waterfall decision, while a returned reason can only reduce permission, so a later listener cannot undo it.
 
 ```ts type-equiv
+/**
+ * A monotonic execution guard evaluated after every `tools/pre-execute`
+ * listener and before the tool body. Returning a reason denies the call;
+ * returning `undefined` leaves it unchanged. Because guards have no allow
+ * result, listener ordering cannot turn a denial back into permission.
+ * @param execution - the identity-protected call after extensible pre-execute policy completed.
+ * @returns a final denial reason, or `undefined` to leave the call allowed.
+ */
 type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
 ```
 
 ```ts type-equiv
+/** The outcome of one tool call. */
 interface ToolExecutionResult {
   content: ContentBlock[]
   isError: boolean
@@ -179,14 +241,8 @@ interface ToolExecutionResult {
    */
   error?: ToolErrorInfo
   /**
-   * Extra model-facing contexts deferred by a composite tool or attached by
-   * `tools/post-execute` listeners for the NEXT request. They are not part of
-   * this call's `content`: the loop accepts them into the active-batch FIFO and
-   * appends them after every recorded `tool/result` when the batch settles, even
-   * when execution is interrupted. The array preserves each context's source,
-   * envelope, metadata, and production order. An accepted outer call keeps
-   * deferred contexts before decision contexts; a block retains only contexts
-   * supplied by the blocking decision.
+   * Model-facing context for the next request, separate from this tool result. The loop
+   * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
    */
   additionalContexts?: HookContext[]
   /**
@@ -206,6 +262,12 @@ The registry materializes and freezes the final accepted result immediately befo
 Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` seams). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
 
 ```ts type-equiv
+/**
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
+ * `ask` runs only after an approval service returns `allowed-once` and otherwise
+ * denies. Input rewriting is excluded because arguments are already logged and
+ * presented.
+ */
 type PreToolDecision =
   | { kind: 'allow' }
   | { kind: 'deny'; reason: string }
@@ -213,6 +275,10 @@ type PreToolDecision =
 ```
 
 ```ts type-equiv
+/**
+ * Post-dispatch decision: accept or replace content, attach context for the next
+ * request, or block by turning corrective feedback into an error result.
+ */
 type PostToolDecision =
   | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
   | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
@@ -227,25 +293,41 @@ Post-policy may replace content; a block becomes an `isError` result containing
 The vocabulary a caller uses to demand a machine-readable result from a subagent (`SubagentStartRequest.outputSchema`, [subagent.md](subagent.md#the-start-request)) or a workflow `agent()` call. It is deliberately NOT full JSON Schema: the schema travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated client-side by `validateStructuredValue` — so every accepted keyword must be one the validator actually enforces, and `assertSupportedOutputSchema` rejects anything else loud (`OutputSchemaError`, listing every violation). Both walkers reason over own enumerable properties only (JSON carries nothing else) and reject non-plain objects (`Date`, `Map`) that would serialize lossily.
 
 ```ts type-equiv
+/** The scalar values `enum`/`const` may carry (finite numbers only). */
 type StructuredScalar = string | number | boolean | null
 ```
 
 ```ts type-equiv
+/** The `type` keywords the subset accepts. */
 type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
 ```
 
 ```ts type-equiv
+/**
+ * One node of the structured-output schema subset. Recursive via `properties`
+ * and `items`; see the module doc for the exact keyword semantics.
+ */
 interface StructuredSchemaNode {
   type: StructuredSchemaType
+  /** Nested property schemas (`type: 'object'` only). */
   properties?: Record<string, StructuredSchemaNode>
+  /** Required property names; each must appear in `properties`. */
   required?: string[]
+  /** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */
   additionalProperties?: boolean
+  /** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */
   items?: StructuredSchemaNode
+  /** Allowed values (scalar types only). */
   enum?: StructuredScalar[]
+  /** The single allowed value (scalar types only). */
   const?: StructuredScalar
+  /** Annotation, ignored for validation. */
   description?: string
+  /** Annotation, ignored for validation. */
   title?: string
+  /** Annotation, ignored for validation (must still be JSON data). */
   default?: unknown
+  /** Annotation, ignored for validation (must still be JSON data). */
   examples?: unknown
 }
 ```
@@ -253,6 +335,7 @@ interface StructuredSchemaNode {
 A schema is an object-rooted node (`enum`/`const` are scalar-only; `description`/`title`/`default`/`examples` are annotations, allowed and ignored but still required to be JSON data — they ride the wire):
 
 ```ts type-equiv
+/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */
 type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }
 ```
 
diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md
index 4edc415039..dcca6355e9 100644
--- a/docs/core-data-structures/user-interaction.md
+++ b/docs/core-data-structures/user-interaction.md
@@ -1,6 +1,6 @@
 # User Interaction
 
-The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-demo` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations.
+The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-demo` selects keyboard-driven `dsh-tui` overlays or `dsh-stdio` readline prompts, and `dsh-acp` maps questions to ACP form elicitations.
 
 Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
 
@@ -9,6 +9,7 @@ Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-int
 `AskUserQuestionOption` is the selectable-choice shape. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
 
 ```ts type-equiv
+/** One selectable answer offered to the user. */
 interface AskUserQuestionOption {
   /** User-facing label. */
   label: string
@@ -22,6 +23,7 @@ interface AskUserQuestionOption {
 `AskUserQuestionItem` is one question in a request. The model supplies a stable `id`, which is echoed back with the answer so batched questions remain routable.
 
 ```ts type-equiv
+/** One question in an ask_user_question request. */
 interface AskUserQuestionItem {
   /** Stable model-provided question id, echoed in the answer. */
   id: string
@@ -41,6 +43,7 @@ interface AskUserQuestionItem {
 `AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer.
 
 ```ts type-equiv
+/** Request for a human answer. */
 interface AskUserQuestionRequest {
   /** Questions to display. */
   questions: AskUserQuestionItem[]
@@ -56,6 +59,7 @@ interface AskUserQuestionRequest {
 Providers return one answer per answered question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices.
 
 ```ts type-equiv
+/** Answer to one question. */
 interface AskUserQuestionAnswerItem {
   /** The answered question id. */
   id: string
@@ -67,6 +71,7 @@ interface AskUserQuestionAnswerItem {
 ```
 
 ```ts type-equiv
+/** The human's answer. */
 interface AskUserQuestionAnswer {
   /** Structured answers keyed by question id. */
   answers: AskUserQuestionAnswerItem[]
@@ -78,6 +83,7 @@ interface AskUserQuestionAnswer {
 Only one provider may be active in a context. Provider registration is effect-bound so HMR/disposal removes the active UI.
 
 ```ts type-equiv
+/** UI-side provider for user questions. */
 interface UserInteractionProvider {
   ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 }
@@ -88,6 +94,7 @@ interface UserInteractionProvider {
 `UserInteractionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `ASK_ABORTED`, or ACP-side cancellation.
 
 ```ts type-equiv
+/** Stable error taxonomy for user-interaction failures. */
 class UserInteractionError extends HarnessError {
   constructor(message: string, code: string, options?: ErrorOptions) {
     super(message, code, options)
diff --git a/docs/core-data-structures/web.md b/docs/core-data-structures/web.md
index 9d79cd96c8..af14f54466 100644
--- a/docs/core-data-structures/web.md
+++ b/docs/core-data-structures/web.md
@@ -13,20 +13,37 @@ Search and fetch share no request schema and no business logic, but they are del
 The model-facing tool argument is just a `query`; `maxResults` is a consumer-owned bound (`dsh-tool-web`'s `searchMaxResults` config, default `8`) passed through the seam and enforced on the way back — if a provider over-returns, the seam truncates `sources[]` and sets `truncated`.
 
 ```ts type-equiv
+/**
+ * What one search-capable backend can return. The model-facing argument is just
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
+ */
 interface WebSearchRequest {
   readonly query: string
   /**
    * Upper bound on returned sources; the seam truncates to it. Omitted = no
-   * bound. `dsh-tool-web` always sets it.
+   * bound. `dsh-tool-web` always sets it. A provider whose API supports a
+   * result-count control (Exa's `numResults`) should apply it at the request
+   * layer as a cost/latency optimization; the seam enforces the bound
+   * regardless.
    */
   readonly maxResults?: number
 }
 ```
 
 ```ts type-equiv
+/**
+ * Normalized search outcome. `content` is optional provider-generated answer
+ * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * when it cut `sources[]` down to `maxResults`.
+ */
 interface WebSearchResult {
+  /** Optional provider-generated answer text, search context, or summary. */
   readonly content?: string
+  /** Citeable sources, already truncated to the request's `maxResults`. */
   readonly sources: readonly WebSearchSource[]
+  /** True when the seam dropped sources to honor `maxResults`. */
   readonly truncated: boolean
 }
 ```
@@ -34,10 +51,17 @@ interface WebSearchResult {
 `content` is optional provider-generated answer text (Exa and DeepSeek return none; Perplexity returns a generated answer). `sources[]` is the portable citation surface. A source always has a `url`; `title`/`snippet`/`publishedAt` are optional because not every provider returns them — Perplexity citations may be URL-only, and forcing adapters to invent the rest would make the seam lie. `dsh-tool-web` renders `title ?? hostname(url)`.
 
 ```ts type-equiv
+/**
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
+ * `publishedAt` are optional because not every provider returns them — forcing
+ * adapters to invent them would make the seam lie (Perplexity citations may be
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
+ */
 interface WebSearchSource {
   readonly url: string
   readonly title?: string
   readonly snippet?: string
+  /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
   readonly publishedAt?: string
 }
 ```
@@ -45,6 +69,12 @@ interface WebSearchSource {
 ## Fetch request and result
 
 ```ts type-equiv
+/**
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
+ * direct execution argument, while presentation and higher-level LLM concerns
+ * belong outside safe retrieval.
+ */
 interface WebFetchRequest {
   readonly url: string
 }
@@ -53,10 +83,20 @@ interface WebFetchRequest {
 HTTP status is part of the fetched resource state, not automatically a failure: a successful network fetch of a `404`/`500` returns a `WebFetchResult` with the status code and a bounded decoded body. `url` is the final URL after allowed redirects. `WebError` is reserved for failures to safely retrieve or represent the resource.
 
 ```ts type-equiv
+/**
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
+ * a result, not an error: the status code is part of the fetched resource
+ * state. {@link WebError} is reserved for failures to safely retrieve or
+ * represent the resource.
+ */
 interface WebFetchResult {
+  /** The final URL after allowed redirects (the request URL is in the request). */
   readonly url: string
+  /** HTTP status code of the fetched response. */
   readonly statusCode: number
+  /** Decoded body, classified by content kind. */
   readonly body: WebFetchBody
+  /** True when the provider capped the decoded body. */
   readonly truncated: boolean
 }
 ```
@@ -64,6 +104,15 @@ interface WebFetchResult {
 `WebFetchBody` is a **closed** discriminated union owned by `dsh-web` (not a merge-extensible map): the provider decodes the kind and `dsh-tool-web` renders it, so a new kind is a coordinated change across known packages, not a plugin extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`, so adding a kind breaks compilation at every consumer until handled. Each arm stays its own object literal even where fields coincide today, leaving room for arm-specific fields later (a future `pdf` body's `pageCount`).
 
 ```ts type-equiv
+/**
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
+ * new kind is a coordinated change across known packages, not a plugin
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
+ * stays its own object literal even where fields coincide today, leaving room
+ * for arm-specific fields later (a `pdf` body's `pageCount`).
+ */
 type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
   | { readonly kind: 'text'; readonly content: string }
diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md
index 4354105e70..40b17a3112 100644
--- a/docs/core-data-structures/workflow.md
+++ b/docs/core-data-structures/workflow.md
@@ -11,11 +11,24 @@ Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/work
 What a caller asks for when starting a run. The tool layer builds this from the model's `{ script, meta, args }` call plus the calling agent; `meta` and `args` are plain JSON DATA (the engine shape-validates `meta` and rejects loud BEFORE anything runs — no script text is ever evaluated to obtain it). `parent` is REQUIRED — every child the script spawns is attributed to it (cwd, lineage, and depth flow through the [subagent seam](subagent.md)).
 
 ```ts type-equiv
+/**
+ * What a caller asks for when starting a workflow run. `meta` and `args` are
+ * plain JSON DATA by the seam contract (the tool builds both from the model's
+ * schema-validated call; the engine validates `meta`'s shape and rejects loud
+ * before anything runs) — an engine never evaluates script text to obtain
+ * them. `parent` is REQUIRED — every `agent()` the script spawns is
+ * attributed to it (cwd, lineage, depth flow through the subagent seam).
+ */
 interface WorkflowStartRequest {
+  /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
   script: string
+  /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
   meta: WorkflowMeta
+  /** Optional input exposed verbatim to the script as the `args` global. */
   args?: unknown
+  /** The agent on whose behalf the run executes (parent of every child). */
   parent: Agent
+  /** Cancels the run when aborted (the tool's `exec.signal`). */
   signal?: AbortSignal
 }
 ```
@@ -25,10 +38,21 @@ interface WorkflowStartRequest {
 The identity block carried as data on the start request (the tool's `meta` parameter; the field vocabulary matches the Claude Code dynamic-workflows meta block). `phases` is progress vocabulary only: `phase()` calls match titles for observers; no execution structure is implied.
 
 ```ts type-equiv
+/**
+ * The script's identity block, provided as plain JSON data alongside the
+ * script body (the model-facing tool carries it as its `meta` parameter) and
+ * validated by the engine before the body runs. `name`/`description` are
+ * required; the rest is optional annotation. The field vocabulary matches the
+ * Claude Code dynamic-workflows meta block.
+ */
 interface WorkflowMeta {
+  /** Short kebab-case workflow name (display + persistence key). */
   name: string
+  /** One-line description of what the workflow does. */
   description: string
+  /** Optional guidance on when this workflow applies (shown in listings). */
   whenToUse?: string
+  /** Optional phase declarations matched by `phase()` calls. */
   phases?: WorkflowPhase[]
 }
 ```
@@ -38,10 +62,27 @@ interface WorkflowMeta {
 The outcome of one run, resolved by `WorkflowRun.result`. `value` is the script's materialized return value — plain host-realm JSON data (`null` when the script returned nothing) — meaningful only for `completed`. `stopReason` is a CLOSED union (engine-owned; consumers may exhaust it): `completed` | `cancelled` | `error`. A non-`completed` reason carries the failure in `error`, and the consumer maps it to an `isError` tool result rather than reporting partial output as success.
 
 ```ts type-equiv
+/**
+ * The outcome of one run, resolved by {@link WorkflowRun.result}. `value` is
+ * the script's materialized return value (plain host-realm JSON data; `null`
+ * when the script returned `undefined`) — meaningful only for `completed`.
+ * A non-`completed` reason carries the failure in `error`; the consumer maps
+ * it to an `isError` tool result rather than reporting partial output.
+ */
 interface WorkflowResult {
+  /** The script's return value (host JSON data; `null` for no return). */
   value: unknown
+  /** Why the run settled. */
   stopReason: WorkflowStopReason
+  /** The failure message (present iff `stopReason` is not `completed`). */
   error?: string
+  /**
+   * How many `agent()` calls the run accepted over its whole lifetime. On a
+   * graceful settlement this is the script-side count (calls still queued for
+   * a concurrency slot included); on a termination path (grace force-settle,
+   * worker death) it degrades to the host-observed count — calls queued
+   * inside a terminated script are unknowable then.
+   */
   agentsStarted: number
 }
 ```
@@ -51,11 +92,20 @@ interface WorkflowResult {
 The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — and once the run is cancelled it SETTLES within the engine's bounded grace even if the script itself never settles (the engine force-settles `cancelled`; the worker-thread engine then terminates the script's worker), so a consumer awaiting `result` is never wedged past a cancellation. `dispose()` = cancel + that bounded settle + child quiescence; it never hangs on a stuck script.
 
 ```ts type-equiv
+/**
+ * Holder-owned live workflow. `result` never rejects and settles within the
+ * engine's cancellation grace; failures resolve through `stopReason`. Consumers
+ * may cancel and must call idempotent `dispose()` on every path to await bounded
+ * script settlement and child quiescence.
+ */
 interface WorkflowRun {
   readonly id: WorkflowRunId
+  /** The validated meta block (available before the body runs). */
   readonly meta: WorkflowMeta
   readonly result: Promise<WorkflowResult>
+  /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is force-settled at the grace). */
   cancel(reason?: string): void
+  /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */
   dispose(): Promise<void>
 }
 ```
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 494eb09922..e5b3feba33 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-development.md: b3c338f03f548b4de4b676850732731323d611f1
-development.zh.md: 20f5c585dd378a7b0a3bd6b0af8ebf7dc5e0fd3c
+development.md: 37811f7215001fc371ac4943fe109dd5512ea8b0
+development.zh.md: 5036e3e75516fcaf063675fc9ab4e63c1fca851a
diff --git a/docs/development.md b/docs/development.md
index b3c338f03f..37811f7215 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -109,12 +109,24 @@ The echo demo does not need API credentials:
 pnpm run demo:echo
 ```
 
-The REPL agent demo uses the real DeepSeek adapter and needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:
+The coding-agent REPL uses the line-oriented readline front door and needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:
 
 ```sh
 pnpm run demo:repl
 ```
 
+The full-screen TUI reuses the coding-agent composition through the pi-tui front door and needs the same credentials:
+
+```sh
+pnpm run demo:tui
+```
+
+The self-referential cordis-agent demo can inspect and modify its live plugin runtime and needs the same credentials:
+
+```sh
+pnpm run demo:cordis
+```
+
 The ACP server agent demo exposes the agent over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:
 
 ```sh
@@ -133,13 +145,13 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ## Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](core-data-structures/core.md) docs paste real type definitions so a reader sees the exact shape. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [core data structures](core-data-structures/core.md) docs paste real type declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
 { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration from source via the TypeScript parser and asserts the block matches it (whitespace- and comment-insensitive, so a doc block may show a clean definition and the prose can carry the semantics). It also enforces a 1:1 correspondence: every `ts type-equiv` block has exactly one manifest entry and vice-versa, so a block can't go silently unchecked and a stale entry can't linger. `doc-typecheck` skips `ts type-equiv` blocks (they aren't standalone-compilable) and excludes them from its opt-out ratio. When you change a documented type, the gate fails until you update the paste; when you add or remove a block, update the manifest in the same change.
+`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate also enforces a 1:1 correspondence: every `ts type-equiv` block has exactly one manifest entry and vice-versa, so a block can't go silently unchecked and a stale entry can't linger. `doc-typecheck` skips `ts type-equiv` blocks (they aren't standalone-compilable) and excludes them from its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a block, update the manifest in the same change.
 
 ## Architecture context
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 20f5c585dd..5036e3e755 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -109,12 +109,24 @@ echo 演示不需要 API 凭证：
 pnpm run demo:echo
 ```
 
-REPL agent 演示使用真实的 DeepSeek 适配器，需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：
+coding-agent REPL 使用面向行的 readline 前端，并需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：
 
 ```sh
 pnpm run demo:repl
 ```
 
+全屏 TUI 通过 pi-tui 前端复用 coding-agent 组装，并需要相同的凭证：
+
+```sh
+pnpm run demo:tui
+```
+
+自指的 cordis-agent 演示可以检查并修改其实时插件运行时，并需要相同的凭证：
+
+```sh
+pnpm run demo:cordis
+```
+
 ACP 服务器 agent 演示通过 JSON-RPC stdio 暴露 agent，同样需要 `DEEPSEEK_API_KEY`：
 
 ```sh
@@ -133,13 +145,13 @@ pnpm run demo:acp
 
 ## 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[核心数据结构](core-data-structures/core.md)文档会把真实类型声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义，语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然；因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然；因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。
 
 ## 架构上下文
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index cfa5160f41..abea24e3a5 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -7,17 +7,17 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:363`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:141`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:150`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`stdio`](../packages/ui/stdio) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:362`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`stdio`](../packages/ui/stdio), [`tui`](../packages/ui/tui) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:141`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio), [`tui`](../packages/ui/tui) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:150`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`stdio`](../packages/ui/stdio), [`tui`](../packages/ui/tui) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`tui`](../packages/ui/tui) |
 | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) |
 | `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:214`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
 | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:169`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:226`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp) |
 | `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:241`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:182`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`stdio`](../packages/ui/stdio) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:159`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`stdio`](../packages/ui/stdio) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:159`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`stdio`](../packages/ui/stdio), [`tui`](../packages/ui/tui) |
 | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:252`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:262`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
@@ -26,10 +26,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:70`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:53`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:40`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:46`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:56`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter), [`workspace-context`](../packages/context/workspace-context) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:78`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:79`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:112`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:86`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:92`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index 60de01ef81..5220cfa81f 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -14,6 +14,7 @@ The process decision behind this index is recorded in [the documentation graph R
 | [capability seams and core services](capability-seams.md) | `hybrid generated` |
 | [echo-agent app composition](../examples/echo-agent/composition.md) | `hybrid generated` |
 | [coding-agent app composition](../examples/coding-agent/composition.md) | `hybrid generated` |
+| [tui-agent app composition](../examples/tui-agent/composition.md) | `hybrid generated` |
 | [cordis-agent app composition](../examples/cordis-agent/composition.md) | `hybrid generated` |
 | [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` |
 | [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 8bc15d6e8e..cd87c161de 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -123,9 +123,9 @@ Follow the Good versions; these sentence-level examples illustrate error categor
 - Good: `A green gate does not mean the translation is correct.`
 
 ### Code block comments — never translate
-- Source code block contains: `# REPL agent demo (needs DEEPSEEK_API_KEY)`
-- Bad: `# REPL agent 演示（需要 DEEPSEEK_API_KEY）`
-- Good: `# REPL agent demo (needs DEEPSEEK_API_KEY)` (byte-identical)
+- Source code block contains: `# readline coding agent (needs DEEPSEEK_API_KEY)`
+- Bad: `# readline 编码 agent（需要 DEEPSEEK_API_KEY）`
+- Good: `# readline coding agent (needs DEEPSEEK_API_KEY)` (byte-identical)
 
 ### Language switcher — English to Chinese
 - Source: `English | [中文](README.zh.md)`
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 83ccdd64c3..c65b31a6fc 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -101,7 +101,6 @@ flowchart TD
     pkg_invariants["invariants"]
     pkg_llm_replay["llm-replay"]
     pkg_loader_smoke["loader-smoke"]
-    pkg_subagent_mock["subagent-mock"]
   end
   subgraph group_ui["packages/ui"]
     pkg_acp["acp"]
@@ -110,6 +109,7 @@ flowchart TD
     pkg_permission["permission"]
     pkg_stdio["stdio"]
     pkg_tool_ask_user["tool-ask-user"]
+    pkg_tui["tui"]
     pkg_user_approval["user-approval"]
     pkg_user_interaction["user-interaction"]
   end
@@ -372,10 +372,6 @@ flowchart TD
   pkg_hooks_claude --> pkg_session_persistence
   pkg_hooks_claude --> pkg_subagent
   pkg_hooks_claude --> pkg_tools
-  pkg_subagent_mock --> pkg_agent
-  pkg_subagent_mock --> pkg_llm
-  pkg_subagent_mock --> pkg_session
-  pkg_subagent_mock --> pkg_subagent
   pkg_jsonrpc --> pkg_agent
   pkg_jsonrpc --> pkg_llm
   pkg_jsonrpc --> pkg_llm_deepseek
@@ -387,6 +383,12 @@ flowchart TD
   pkg_stdio --> pkg_llm
   pkg_stdio --> pkg_session
   pkg_stdio --> pkg_user_interaction
+  pkg_tui --> pkg_agent
+  pkg_tui --> pkg_agent_loop
+  pkg_tui --> pkg_llm
+  pkg_tui --> pkg_session
+  pkg_tui --> pkg_tools
+  pkg_tui --> pkg_user_interaction
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_execution
   pkg_agent_spine_demo --> pkg_agent_loop
@@ -433,6 +435,7 @@ flowchart TD
   pkg_stdio_demo --> pkg_stdio
   pkg_stdio_demo --> pkg_tool_ask_user
   pkg_stdio_demo --> pkg_tools
+  pkg_stdio_demo --> pkg_tui
   pkg_stdio_demo --> pkg_user_interaction
   pkg_stdio_demo --> pkg_workspace_context
 ```
@@ -519,12 +522,12 @@ flowchart TD
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`stdio`](../packages/ui/stdio) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`user-interaction`](../packages/ui/user-interaction) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-execution`](../packages/core/agent-execution), [`agent-loop`](../packages/core/agent-loop), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
-| [`stdio-demo`](../packages/examples/stdio-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`stdio-demo`](../packages/examples/stdio-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 34869b4fd3..73d395af4b 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -22,8 +22,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 |---|---|
 | [Prune dead public and result surface](proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md) | 2026-07-04 |
 | [Make JSON-RPC completion and transport directional](proposed/simplification/2026-07-19-make-jsonrpc-directional.md) | 2026-07-19 |
-| [Retire the standalone subagent mock package](proposed/simplification/2026-07-19-retire-subagent-mock-package.md) | 2026-07-19 |
-| [Use one surface manager per session](proposed/simplification/2026-07-19-use-one-session-surface-manager.md) | 2026-07-19 |
 
 ### Architecture
 
@@ -89,6 +87,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Session query relationship tracing](implemented/feature/2026-07-13-session-query-tracing.md) | 2026-07-13 |
 | [Optional time-context plugin](implemented/feature/2026-07-14-time-context-plugin.md) | 2026-07-14 |
 | [Durable per-step time context](implemented/feature/2026-07-16-durable-per-step-time-context.md) | 2026-07-16 |
+| [Dedicated full-screen TUI front door](implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) | 2026-07-17 |
 
 ### Simplification
 
@@ -117,6 +116,8 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Drop unconsumed skill provider events](implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md) | 2026-07-12 |
 | [Prune unused web seam fields](implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md) | 2026-07-12 |
 | [Simplify session-log representation](implemented/simplification/2026-07-12-simplify-session-log-representation.md) | 2026-07-12 |
+| [Retire the standalone subagent mock package](implemented/simplification/2026-07-19-retire-subagent-mock-package.md) | 2026-07-19 |
+| [Use one surface manager per session](implemented/simplification/2026-07-19-use-one-session-surface-manager.md) | 2026-07-19 |
 
 ### Architecture
 
@@ -213,6 +214,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Single-source the acp-agent replay config](implemented/testing/2026-07-04-single-source-acp-replay-config.md) | 2026-07-04 |
 | [Pin request-header content in one snapshot scenario](implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md) | 2026-07-06 |
 | [Extract the ACP snapshot suite into a support package](implemented/testing/2026-07-08-shared-acp-snapshot-package.md) | 2026-07-08 |
+| [Snapshot semantic terminal state for the TUI](implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) | 2026-07-18 |
 
 ## Rejected
 
diff --git a/docs/rfc/implemented/architecture/2026-06-18-session-surface.md b/docs/rfc/implemented/architecture/2026-06-18-session-surface.md
index 7c6c5b00d0..d639fe2917 100644
--- a/docs/rfc/implemented/architecture/2026-06-18-session-surface.md
+++ b/docs/rfc/implemented/architecture/2026-06-18-session-surface.md
@@ -31,7 +31,7 @@ export type SurfaceOp =
 
 ### SurfaceManager: delta-based, not full rebuild
 
-A `SurfaceManager` class (private to `Session`) maintains one ordered `number[]` of event seqs. It tracks `_lastProcessedSeq` and processes only the new events since the last access rather than rescanning the entire log. Because the log is append-only, prior events never change; a seeded log is simply the initial suffix folded on first access. Replace locates its inclusive endpoints by array position and splices the replacement seq into that range; no link objects or seq-to-node map duplicate the order.
+A `Session` owns one `SurfaceManager` that maintains an ordered `number[]` of event seqs. The manager validates each seed or append candidate without applying it before commit, then processes only committed events since its previous synchronization rather than rescanning the entire log. `Session.surface` exposes the same manager through the readonly `SessionSurface` contract, so acceptance, derived history, compaction, and workspace context share one incremental state. Replace locates its inclusive endpoints by array position and splices the replacement seq into that range; no second manager, link objects, or seq-to-node map duplicates the order.
 
 Delta processing is O(1) when no new events and O(new events) when new events arrive.
 
@@ -60,7 +60,7 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 
 ## Consequences
 
-- **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array; `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
+- **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
 - **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance.
 - **`packages/session-persistence/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
 - **`packages/support/invariants`**: Surface-related validation rules.
diff --git a/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md b/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
index 11824bcf63..3f44940848 100644
--- a/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-> The full seam is shipped: the `dsh-subagent` interface, the `dsh-subagent-mock` test backend, and the `dsh-tool-subagent` consumer; the two in-process backends (`dsh-subagent-spawn`, `dsh-subagent-fork`); the nested-agent snapshot infrastructure ([per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md)); and the out-of-process `dsh-subagent-acp` backend ([its RFC](2026-06-22-acp-subagent-backend.md)).
+> The full seam is shipped: the `dsh-subagent` interface and `dsh-tool-subagent` consumer; the two in-process backends (`dsh-subagent-spawn`, `dsh-subagent-fork`); the nested-agent snapshot infrastructure ([per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md)); and the out-of-process `dsh-subagent-acp` backend ([its RFC](2026-06-22-acp-subagent-backend.md)).
 
 ## Problem
 
@@ -32,7 +32,6 @@ A new package group `packages/subagent/`:
 | `@deepseek-ai/dsh-subagent-spawn` | implementation: a fresh in-process child via `ctx.agents.create` |
 | `@deepseek-ai/dsh-subagent-fork` | implementation: an in-process child seeded with a snapshot of the parent's log |
 | `@deepseek-ai/dsh-subagent-acp` | implementation: an ACP client driving a configured child process |
-| `@deepseek-ai/dsh-subagent-mock` | support: a scripted provider for testing the seam through the real load path |
 | `@deepseek-ai/dsh-tool-subagent` | consumer: the model-facing `subagent` tool over `ctx.subagents` |
 
 ### The primitive: async `start → SubagentRun`
@@ -62,7 +61,7 @@ Each subagent runs in its **own `Session`** (own id, `parentSession` lineage), p
 
 ## Testing
 
-The seam is tested through the real Cordis Loader/export path, which catches the export-shape failure described in [postmortem 0001](../../../postmortem/0001-acp-default-export-drops-inject.md). Registry tests cover reload safety, duplicate names, and start-time capability rejection; nested-agent scenarios replay keylessly through [per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md); in-process backends also have real-loop unit tests and a with-key e2e.
+Registry and tool tests replace only the nondeterministic child boundary with a package-local scripted provider while exercising the real `SubagentService`, lifecycle, task integration, and model-facing tool. Provider and consumer export shapes retain their Loader regression coverage for the failure described in [postmortem 0001](../../../postmortem/0001-acp-default-export-drops-inject.md). Registry tests cover reload safety, duplicate names, and start-time capability rejection; nested-agent scenarios replay keylessly through [per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md); in-process backends also have real-loop unit tests and a with-key e2e.
 
 ## Consequences
 
diff --git a/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml
new file mode 100644
index 0000000000..d57bf423f5
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-17-dedicated-full-screen-tui-front-door.md: 5e66b85fa23ef394b88fd16880cf218ac5cc2202
+2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 4ccfde2d633115a41b24227ee78f7e4010bd70ee
diff --git a/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
new file mode 100644
index 0000000000..5e66b85fa2
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
@@ -0,0 +1,48 @@
+# RFC: Dedicated full-screen TUI front door
+
+Status: implemented
+
+English | [中文](2026-07-17-dedicated-full-screen-tui-front-door.zh.md)
+
+## Problem
+
+The line-oriented `@deepseek-ai/dsh-stdio` front door works in pipes and ordinary terminals, but a full-screen coding interface must own raw input, differential screen drawing, cursor state, overlays, and terminal restoration. Combining those contracts in one UI plugin couples the pipe-safe path to a TTY-only lifecycle and makes it unclear which terminal behavior a composition selects.
+
+The interactive channel must remain a Cordis plugin over the same agent, session, tool, and user-interaction services as every other front door. It needs to resume durable history, follow compaction replacements, display tool-owned presentation, and restore the terminal on startup failure and disposal. A standalone chat application or a second agent composition would duplicate behavior outside the plugin graph.
+
+## Decision
+
+DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
+
+The app layer selects a concrete terminal front door before mounting it. `@deepseek-ai/dsh-stdio-demo` can resolve `auto` from the two process streams, while the `coding-agent` and `tui-agent` leaves explicitly select readline and TUI respectively. The TUI leaf reuses the coding agent's backend and tool composition through an asserted include patch, so the three runnable agent leaves remain symmetric without duplicating deployment choices.
+
+The selected front door receives the exact generated or resumed `SessionId` used by the pre-created agent. It mounts before the agent composition, waits for the matching root agent, and enters full-screen mode only after that agent exists. A matching `agent-loop/config-start-failed` event is therefore reported before screen takeover and exits with status 1.
+
+### Session projection and interaction
+
+The TUI rebuilds the transcript from the active `session.surface` and reprojects it whenever an event carries a `surfaceOp`, so resumed and compacted history matches the model-visible conversation. It renders Markdown text and reasoning, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Pending chunks and tool calls update the same components that completed events settle.
+
+Editor input calls `agent.send()` while idle and `agent.steer()` while a turn is running. Cancellation, reasoning visibility, tool-card expansion, redraw, transcript clearing, and exit are terminal-only controls. The plugin registers the shared `userInteraction` provider and presents questions as queued keyboard overlays; agent behavior and answer logging remain owned by their existing services.
+
+### Terminal ownership
+
+Before model output, session data, tool presentation, questions, configuration, or diagnostics reach pi-tui or the terminal title, `displayText()` renders C0 and C1 controls other than line feeds as visible hexadecimal escapes. Only the TUI and pi-tui create ANSI control sequences.
+
+The built-in palette uses standard 16-color ANSI foregrounds and SGR attributes, keeps body text and backgrounds at terminal defaults, and uses reverse video for selection. Host terminals therefore remap the interface for light and dark themes without a TUI-specific theme setting; `color: false` removes styling.
+
+## Verification
+
+The implemented [TUI terminal-state snapshot RFC](../testing/2026-07-18-tui-terminal-state-snapshots.md) owns the four-layer verification contract: direct behavior tests, transient semantic terminal snapshots, recorded JSONL journeys through production tools, and Loader/PTY smoke tests. The package README owns configuration, commands, model-visible effects, and current limitations.
+
+## Alternatives considered
+
+- **Keep readline and full-screen modes inside `@deepseek-ai/dsh-stdio`** — rejected because line-oriented output and differential TTY rendering have different dependencies, input rules, logging ownership, and teardown obligations. Separate packages keep the pipe-safe contract small and explicit.
+- **Let the TUI plugin silently downgrade when either stream is not a TTY** — rejected because a fallback hides deployment mistakes and changes interaction semantics. The app bundle may select a front door with `auto`; an explicitly mounted TUI fails loud.
+- **Keep TUI wiring and tests under the readline `coding-agent` leaf** — rejected because one leaf would represent two distinct front doors and break symmetry with `acp-agent`. A dedicated `tui-agent` leaf owns TUI overlays and tests while reusing the coding agent's backend composition.
+
+## Consequences
+
+- Interactive terminal work gains a stateful Markdown, card, plan, and question interface without changing the line-oriented protocol used by pipes and automation.
+- The TUI carries a pi-tui dependency and a strict TTY requirement; non-TTY deployments select `@deepseek-ai/dsh-stdio` at composition time.
+- Session projection makes resume and compaction consistent with the durable conversation, but one configured session owns the transcript and editor.
+- Tool packages extend terminal cards through their existing presentation methods without adding tool-specific branches to the TUI.
diff --git a/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
new file mode 100644
index 0000000000..4ccfde2d63
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
@@ -0,0 +1,48 @@
+# RFC: 独立的全屏 TUI 入口
+
+Status: implemented
+
+[English](2026-07-17-dedicated-full-screen-tui-front-door.md) | 中文
+
+## 问题
+
+逐行输出的 `@deepseek-ai/dsh-stdio` 入口适用于管道和普通终端，但全屏编码界面必须负责原始输入、差分绘制、光标状态、浮层和终端恢复。把这两类契约合并到一个 UI 插件中，会迫使管道安全路径依赖仅适用于 TTY 的生命周期，也使组合无法明确表达所选终端行为。
+
+交互通道必须继续作为 Cordis 插件，使用与其他入口相同的 agent（智能体）、会话、工具和用户交互服务。它需要恢复持久历史、跟随压缩替换、显示工具自有的呈现内容，并在启动失败和资源释放时恢复终端。独立聊天应用或第二套 agent 组合会在插件图之外重复实现这些行为。
+
+## 决策
+
+DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
+
+应用组合层在挂载前选择具体的终端入口。`@deepseek-ai/dsh-stdio-demo` 可以根据两个进程流通过 `auto` 作出选择，`coding-agent` 和 `tui-agent` 叶节点则分别明确选择 readline 与 TUI。TUI 叶节点通过带断言的 include patch 复用 coding agent 的后端和工具组合，使三个可运行的 agent 叶节点保持对称，同时避免重复部署选项。
+
+所选入口接收预创建 agent 使用的同一个新建或恢复 `SessionId`。入口先于 agent 组合挂载，等待相符的根 agent 出现，然后才进入全屏模式。因此，相符的 `agent-loop/config-start-failed` 事件会在接管屏幕前报告，并以状态码 1 退出。
+
+### 会话投影与交互
+
+TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。
+
+agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。插件注册共享的 `userInteraction` 提供方，以排队的键盘浮层呈现问题；agent 行为和答案日志仍由既有服务负责。
+
+### 终端所有权
+
+在模型输出、会话数据、工具呈现、问题、配置或诊断信息进入 pi-tui 或终端标题前，`displayText()` 会把换行之外的 C0 和 C1 控制字符显示为十六进制转义文本。只有 TUI 和 pi-tui 可以生成 ANSI 控制序列。
+
+内置配色仅使用标准 16 色 ANSI 前景色和 SGR 属性，正文文字和背景沿用终端默认值，选中项使用反显。因此，宿主终端可以直接按浅色或深色主题重映射界面，无需 TUI 专用主题设置；`color: false` 会移除样式。
+
+## 验证
+
+已实现的 [TUI 终端状态快照 RFC](../testing/2026-07-18-tui-terminal-state-snapshots.md) 规定四层验证契约：直接行为测试、瞬态语义终端快照、通过生产工具执行的已录制 JSONL 流程，以及 Loader/PTY 冒烟测试。包（package）README 负责记录配置、命令、模型可见效果和当前限制。
+
+## 曾考虑的替代方案
+
+- **把 readline 与全屏模式都保留在 `@deepseek-ai/dsh-stdio` 中**：不予采纳，因为逐行输出和差分 TTY 渲染具有不同的依赖、输入规则、日志所有权和资源清理义务。拆分为独立包可以让管道安全契约保持精简、明确。
+- **当任一进程流不是 TTY 时，让 TUI 插件静默降级**：不予采纳，因为回退会掩盖部署错误并改变交互语义。应用包可以通过 `auto` 选择入口；明确挂载的 TUI 会快速失败。
+- **把 TUI 接线与测试保留在 readline `coding-agent` 叶节点下**：不予采纳，因为一个叶节点会代表两个不同入口，也会破坏它与 `acp-agent` 的对称性。独立的 `tui-agent` 叶节点负责 TUI 浮层和测试，同时复用 coding agent 的后端组合。
+
+## 后果
+
+- 交互式终端获得带状态的 Markdown、卡片、计划和提问界面，同时不会改变管道与自动化使用的逐行协议。
+- TUI 会引入 pi-tui 依赖并严格要求 TTY；非 TTY 部署在组合时选择 `@deepseek-ai/dsh-stdio`。
+- 会话投影使恢复和压缩与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。
+- 工具包通过既有呈现方法扩展终端卡片，无需在 TUI 中增加工具专用分支。
diff --git a/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md b/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
index aaac6fbd3c..bf70879c71 100644
--- a/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -10,7 +10,7 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t
 
 ## Decision
 
-A new `docs/core-data-structures/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type definition byte-identical to its source.
+A new `docs/core-data-structures/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
 
 ### What counts as "core" — the spine-vs-seam line
 
@@ -27,10 +27,10 @@ The rule that settled the remaining cases: ***the type you write, hold, or recei
 
 ### The `ts type-equiv` mechanism — literal AND drift-proof
 
-The durability requirement was specific: the doc should show the **literal** current type definition (so a reader sees the real shape, not a paraphrase) **and** be mechanically guaranteed to match source. The repo already compiles fenced ` ```ts ` blocks (`doc-typecheck`), but a real typechecked block needs import noise and proves only *assignability*, not *byte-equality* — a renamed field with the same type would pass. So:
+The durability requirement was specific: the doc shows the **literal** current type declaration and original JSDoc (so a reader sees the real shape and source contract, not a paraphrase) **and** is mechanically guaranteed to match source. The repo already compiles fenced ` ```ts ` blocks (`doc-typecheck`), but a real typechecked block needs import noise and proves only *assignability* — a renamed field or changed JSDoc can pass. So:
 
-- Type definitions are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. `doc-typecheck` recognizes the fence and skips it (a bare definition is not standalone-compilable), and **excludes it from the opt-out ratio** — it is a separately-checked category, not an unchecked sketch.
-- A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts a **verbatim source match** against the declared symbol — chosen over a compiled `_Check` assertion precisely because byte-equality, not assignability, is the property we want.
+- Type declarations and their JSDoc are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. `doc-typecheck` recognizes the fence and skips it (a bare definition is not standalone-compilable), and **excludes it from the opt-out ratio** — it is a separately-checked category, not an unchecked sketch.
+- A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts that its declaration structure and every JSDoc comment match the declared symbol, ignoring only formatting whitespace and non-JSDoc comments. This is chosen over a compiled `_Check` assertion because source names and documentation identity, not assignability, are the properties the catalog preserves.
 - Provenance lives in a central `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence**: every type-equiv block has exactly one manifest entry and vice versa, so a block can never be silently unchecked and an entry can never rot.
 - Wired into `doc-sync`, so it runs in the same lefthook pre-push and CI paths as the other doc gates.
 
@@ -41,7 +41,7 @@ The durability requirement was specific: the doc should show the **literal** cur
 ## Alternatives considered
 
 - **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-seam structure won.
-- **A compiled `_Check` assignability assertion** instead of the verbatim source match — rejected because byte-equality, not assignability, is the property we want: a renamed field with the same type would pass assignability.
+- **A compiled `_Check` assignability assertion** instead of the source match — rejected because assignability does not preserve names or JSDoc: a renamed field with the same type or a changed contract comment would pass.
 - **Provenance as directive comments in the prose** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
 
 ## Verification lesson
diff --git a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml
similarity index 62%
rename from docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml
rename to docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml
index 37c3c8b508..b86d9405e0 100644
--- a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml
+++ b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-19-retire-subagent-mock-package.md: 2731d35448cbc4dc9db4c92579c35202a53eefdd
-2026-07-19-retire-subagent-mock-package.zh.md: 919c56502227157465277cc07c23fb7096763684
+2026-07-19-retire-subagent-mock-package.md: 47174d22eaf27c5a5509280793dd50d70c542d00
+2026-07-19-retire-subagent-mock-package.zh.md: bfad78e1912f9d5153196df3fea2494c88436a91
diff --git a/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.md b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.md
new file mode 100644
index 0000000000..47174d22ea
--- /dev/null
+++ b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.md
@@ -0,0 +1,34 @@
+# RFC: Retire the standalone subagent mock package
+
+Status: implemented
+
+English | [中文](2026-07-19-retire-subagent-mock-package.zh.md)
+
+## Problem
+
+`@deepseek-ai/dsh-subagent-mock` was a configurable test double packaged as a workspace plugin. Its only external consumers were the `tool-subagent` unit suite and the tool-catalog generator; no runtime package, example, snapshot configuration, or real provider loaded it.
+
+That narrow fixture carried a manifest, exports, peer and development dependencies, project references, package README obligations, Loader composition tests, module-graph membership, and documentation exceptions. The tool-catalog generator mounted it only to make production consumers register their schemas and never executed a child.
+
+## Decision
+
+The standalone package is deleted. Its scripted child behavior now lives in `packages/subagent/tool-subagent/tests/scripted-provider.ts`, where tests mount the real `SubagentService`, provider registry, tool implementation, and task runtime while replacing only the nondeterministic child boundary.
+
+The local fixture retains deterministic replies, structured results, stop reasons, cancellation before and after publication, conversation-inheritance descriptors, and effect-scoped disposal. Package-specific Schemastery and Loader-export tests disappear because the fixture is no longer a deployable plugin.
+
+The tool-catalog generator registers a minimal local `SubagentProvider` descriptor before mounting `ToolSubagent` or the workflow engine. The descriptor cannot start a child; it exists only to satisfy production load-time dependencies while harvesting schemas from the real consumers.
+
+Workspace project references, package dependencies, lockfile entries, graph metadata, support-package prose, config-catalog entries, and README gate exceptions no longer name the retired package.
+
+## Alternatives considered
+
+**Keep a reusable mock package for future tests.** Reuse never materialized outside one test file and one generator. A future second behavioral consumer can extract a shared fixture after its contract is known; pre-packaging it made test infrastructure look like a supported backend.
+
+**Generate subagent schemas without mounting production consumers.** Hand-constructing or importing schemas would weaken the catalog check that the real registry and tool composition expose the documented shape. A minimal provider descriptor preserves that check without carrying executable fake-backend behavior.
+
+## Consequences
+
+- The workspace has one fewer deployable package and no test-only node in the capability or module graphs.
+- `tool-subagent` tests retain foreground, background-task, lifecycle, cancellation, reply, stop-reason, and structured-result coverage through production services.
+- Tool-catalog output remains generated from production registrations and is byte-for-byte unchanged.
+- Runtime and example packages gain no dependency on test fixtures.
diff --git a/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.zh.md b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.zh.md
new file mode 100644
index 0000000000..bfad78e191
--- /dev/null
+++ b/docs/rfc/implemented/simplification/2026-07-19-retire-subagent-mock-package.zh.md
@@ -0,0 +1,34 @@
+# RFC: 撤销独立的 subagent mock 包
+
+Status: implemented
+
+[English](2026-07-19-retire-subagent-mock-package.md) | 中文
+
+## 问题
+
+`@deepseek-ai/dsh-subagent-mock` 曾是一个以工作区插件形式发布的可配置测试替身。它仅有两个外部消费方：`tool-subagent` 单元测试和工具目录生成器；运行时包、示例、快照配置和真实提供方都不会加载它。
+
+这个用途狭窄的 fixture（测试前置数据）需要维护 manifest（元数据清单）、导出、对等依赖（peer dependency）与开发依赖、项目引用、包（package）README 契约、Loader 组合测试、模块图成员关系以及文档例外。工具目录生成器挂载它，只是为了让生产消费方注册 schema，并不会执行子 agent。
+
+## 决策
+
+删除独立包。脚本化子 agent 行为现位于 `packages/subagent/tool-subagent/tests/scripted-provider.ts`；测试挂载真实的 `SubagentService`、提供方注册表、工具实现和任务运行时，只替换具有不确定性的子 agent 边界。
+
+本地 fixture 保留确定性回复、结构化结果、停止原因、发布前后的取消、对话继承描述和作用域化的 dispose（资源释放）覆盖。由于 fixture 不再是可部署插件，删除包专用的 Schemastery 与 Loader 导出测试。
+
+工具目录生成器在挂载 `ToolSubagent` 或工作流引擎之前，注册一个最小本地 `SubagentProvider` 描述。该描述无法启动子 agent；它只用于满足生产消费方的加载时依赖，同时从真实消费方提取 schema。
+
+工作区项目引用、包依赖、锁文件条目、图元数据、支持包说明、配置目录条目和 README 门禁例外不再提及已撤销的包。
+
+## 备选方案
+
+**为未来测试保留可复用 mock 包。** 除一个测试文件和一个生成器外，复用需求始终没有出现。未来产生第二个行为消费方时，可以在共享契约明确后再提取 fixture；提前将其打包会使测试基础设施看起来像受支持的后端。
+
+**不挂载生产消费方，直接生成 subagent schema。** 手工构造或直接导入 schema，会削弱目录门禁对真实注册表与工具组合是否公开文档结构的校验。最小提供方描述能保留该校验，而无需携带可执行的虚假后端行为。
+
+## 影响
+
+- 工作区减少一个可部署包，能力图与模块图也不再包含测试专用节点。
+- `tool-subagent` 测试继续通过生产服务覆盖前台、后台任务、生命周期、取消、回复、停止原因和结构化结果。
+- 工具目录输出仍根据生产注册生成，并保持字节级一致。
+- 运行时包与示例包都不会依赖测试 fixture。
diff --git a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml
similarity index 61%
rename from docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml
rename to docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml
index 185d7af4ac..55a113d22b 100644
--- a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml
+++ b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-19-use-one-session-surface-manager.md: 0e4fa14b21f5054e1ace425712506c5c060f2251
-2026-07-19-use-one-session-surface-manager.zh.md: 26126310eefaf56aa45efc428a54e65f0cf35947
+2026-07-19-use-one-session-surface-manager.md: 0c0fd70717ff4b49e8817e88592d0781d9ccbd09
+2026-07-19-use-one-session-surface-manager.zh.md: 6d11c9bb475b0ee5a568f96678d0251f1160dda3
diff --git a/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.md b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.md
new file mode 100644
index 0000000000..0c0fd70717
--- /dev/null
+++ b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.md
@@ -0,0 +1,37 @@
+# RFC: Use one surface manager per session
+
+Status: implemented
+
+English | [中文](2026-07-19-use-one-session-surface-manager.zh.md)
+
+## Problem
+
+`Session` maintained two `SurfaceManager` instances over the same append-only event log. One validated seed and append candidates, while a second lazy instance independently folded committed events for `session.surface`, derived messages, compaction, and workspace context. Once the public surface had been read, every later event advanced duplicate node and replacement-generation state without creating a separate authority or failure boundary.
+
+## Decision
+
+Each `Session` owns one eagerly constructed `SurfaceManager`. Seed and append acceptance call `validateNext()` on that manager before committing an event, and `session.surface` returns the same object through this readonly contract:
+
+```ts
+export interface SessionSurface {
+  readonly nodes: readonly number[]
+  readonly replaceGeneration: number
+}
+```
+
+Candidate validation remains atomic. `validateNext()` may synchronize committed log entries, but it only plans the uncommitted candidate. The candidate enters manager state after `log.push()` and the next delta synchronization, so surface validation failures and pre-commit `internal/dispatch` vetoes leave no phantom node or replacement generation.
+
+`foldSurface()` remains the detached full-log replay function for offline validation and reconstruction. It uses the same transitions and agrees with the live manager for every committed prefix without sharing mutable state.
+
+## Alternatives considered
+
+**Keep acceptance and projection state separate.** Separate instances appeared to isolate public reads from validation, but callers already receive borrowed surface state and the declared readonly contract prevents ordinary mutation. Duplicating the manager was not a runtime trust boundary.
+
+**Recompute the public surface from the full log on every access.** This removed duplicate cached state but gave up incremental derivation and made repeated request construction scale with complete session history.
+
+## Consequences
+
+- Acceptance, `session.surface`, derived messages, compaction, and workspace context observe one incremental state.
+- `Session.surface` exposes no validation method, while its object identity and borrowed readonly node array remain stable.
+- A hostile cast can still corrupt borrowed state; JavaScript callers that deliberately bypass the readonly contract remain outside the supported same-process boundary.
+- Surface, seed, dispatch-veto, request-reconstruction, compaction, and workspace-context tests exercise the shared manager and detached replay paths.
diff --git a/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.zh.md b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.zh.md
new file mode 100644
index 0000000000..6d11c9bb47
--- /dev/null
+++ b/docs/rfc/implemented/simplification/2026-07-19-use-one-session-surface-manager.zh.md
@@ -0,0 +1,37 @@
+# RFC: 每个会话只使用一个表层管理器
+
+Status: implemented
+
+[English](2026-07-19-use-one-session-surface-manager.md) | 中文
+
+## 问题
+
+`Session` 曾针对同一份仅追加事件日志维护两个 `SurfaceManager` 实例。一个实例负责校验种子事件和追加候选事件，另一个延迟创建的实例则独立折叠已提交事件，供 `session.surface`、派生消息、压缩（compaction）和工作区上下文使用。一旦读取公共表层，之后的每个事件都会推进两份重复的节点状态与替换代数状态，却没有形成独立真源或失败边界。
+
+## 决策
+
+每个 `Session` 主动创建并只持有一个 `SurfaceManager`。种子事件与追加事件的接纳流程在提交事件之前调用该管理器的 `validateNext()`，`session.surface` 则通过以下只读契约返回同一个对象：
+
+```ts
+export interface SessionSurface {
+  readonly nodes: readonly number[]
+  readonly replaceGeneration: number
+}
+```
+
+候选事件校验仍保持原子性。`validateNext()` 可以同步已提交的日志事件，但对尚未提交的候选事件只制定变更计划。候选事件在 `log.push()` 之后、下一次增量同步时才进入管理器状态，因此表层校验失败或提交前 `internal/dispatch` 否决都不会留下虚假节点或替换代数。
+
+`foldSurface()` 仍是离线校验与重建使用的分离式完整日志回放函数。它使用相同的状态转换，并且对每个已提交前缀都与活跃管理器一致，但不共享可变状态。
+
+## 备选方案
+
+**继续分离接纳状态与投影视图。** 两个独立实例看似能够隔离公共读取和校验，但调用方取得的本来就是借用的表层状态，声明的只读契约会阻止普通修改。复制管理器并不能构成运行时信任边界。
+
+**每次读取都根据完整日志重新计算公共表层。** 该方案能消除重复缓存状态，但会放弃增量派生，使每次请求构造都随完整会话历史增长。
+
+## 影响
+
+- 接纳流程、`session.surface`、派生消息、压缩和工作区上下文观察同一份增量状态。
+- `Session.surface` 不暴露校验方法，同时保持对象标识和借用的只读节点数组稳定。
+- 恶意类型断言仍可破坏借用状态；刻意绕过只读契约的 JavaScript 调用方不属于受支持的同进程边界。
+- 表层、种子、调度否决、请求重建、压缩和工作区上下文测试覆盖共享管理器与分离回放路径。
diff --git a/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml
new file mode 100644
index 0000000000..b68f7e7e78
--- /dev/null
+++ b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-18-tui-terminal-state-snapshots.md: 280c2b4faec3bd5e14a24a5df7bc901ad31718cd
+2026-07-18-tui-terminal-state-snapshots.zh.md: d1c609c6ce511bba1f498b72444af662b4444578
diff --git a/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md
new file mode 100644
index 0000000000..280c2b4fae
--- /dev/null
+++ b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md
@@ -0,0 +1,70 @@
+# RFC: Snapshot semantic terminal state for the TUI
+
+Status: implemented
+
+English | [中文](2026-07-18-tui-terminal-state-snapshots.zh.md)
+
+## Problem
+
+The TUI is a stateful renderer. Its user-visible result depends on ANSI parsing, differential frames, wrapping, scrollback, viewport position, terminal width, focus, cursor state, and each tool's presentation intent. Unit tests that collect `Terminal.write()` fragments can prove event handling, but they cannot prove the final screen a terminal displays. The same screen may also be emitted through different write fragments, so pinning those fragments creates false regressions.
+
+Component-line snapshots stop before ANSI reaches a terminal and miss cursor movement, clearing, styling, overlay composition, and reflow. Raster screenshots include font and platform rendering noise that is unrelated to the TUI contract. A completed flow built by directly appending plausible session events has another blind spot: it proves the renderer accepts those shapes, not that the production agent loop and tool implementations produce them.
+
+The TUI therefore needs a deterministic, reviewable representation of terminal state, recorded model journeys that execute the real downstream stack, and a smaller test at the real process and PTY boundary.
+
+## Decision
+
+TUI coverage has four complementary layers:
+
+1. `packages/ui/tui/tests/tui.spec.ts` tests event mapping, input routing, disposal, and error behavior directly.
+2. `packages/ui/tui/tests/tui.snapshot.ts` mounts the production TUI against a headless terminal emulator for transient states that a completed session log cannot retain: in-flight streaming, pending tool calls, overlays, expansion, compaction reflow, errors, and shutdown.
+3. `examples/tui-agent/tests/tui.snapshot.ts` replays committed JSONL session logs through the production agent loop and real tools, then compares the resulting semantic terminal state.
+4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real Loader composition in a PTY, drives a scripted conversation through streaming and `ask_user_question`, and verifies startup, input, exit, failure reporting, and terminal restoration.
+
+The runnable TUI has its own `examples/tui-agent` leaf beside the readline `coding-agent` and `acp-agent` leaves. It reuses the coding agent's backend and tool composition through an asserted include patch while fixing the shared terminal app to `ui.mode: tui`; TUI snapshots and PTY tests live with that leaf.
+
+### Recorded-session replay
+
+Each example-level scenario directory owns `session.jsonl`, optional child logs `session.<n>.jsonl`, and `terminal.golden.txt`. The primary log supplies user-authored `user/message` prompts and the recorded `assistant/chunk` sequence. `dsh-llm-replay` derives one model-call script per session, binds child logs to fresh child sessions, and is the only mocked boundary. The agent loop, bash and filesystem implementations, Code Mode worker, subagent provider, workflow worker, Cordis tools, presenters, and TUI are production implementations.
+
+The suite rejects a journey when its tool-call sequence differs, an expected event count is missing, a tool result is an error, a turn ends in error, a workflow lifecycle is incomplete, or the live child-session count differs from the fixture set. These assertions prevent an attractive terminal golden from hiding a failed or bypassed production path.
+
+The live-model fixtures use `DSH_SNAPSHOT=record`; record mode rewrites their primary and child JSONL logs and terminal goldens. The deterministic Cordis toolchain keeps an authored complete JSONL script because reliably coercing a live model through five exact tool boundaries and two children is not a stable recording contract. `DSH_SNAPSHOT=refresh` replays every committed script keylessly and rewrites only derived terminal goldens. Plain replay compares without writing, and unknown mode values fail loud.
+
+### Semantic terminal projection
+
+The package-local `HeadlessTerminal` implements the same pi-tui `Terminal` interface as the process terminal and feeds every ANSI write into the pinned `@xterm/headless` parser. Snapshot code waits for synchronized frames to quiesce before reading state, so a checkpoint represents a completed screen rather than a timer-dependent write prefix.
+
+Each golden projects dimensions, active-buffer and viewport coordinates, lifecycle and cursor state, rows, wrap markers, and non-default style ranges into text. Scroll-heavy cards capture the used buffer; overlays capture the visible viewport. Text and style remain separate so a reviewer can distinguish content changes from presentation changes without decoding ANSI bytes.
+
+Every checkpoint enforces theme independence across the complete terminal state: no RGB colors, no palette entries beyond ANSI 0–15, and no explicit background colors. Reverse video remains valid for selection because it uses terminal defaults. Both suites own closed inventories that reject missing scenarios, missing checkpoints, and orphaned golden files.
+
+### Required scenario matrix
+
+| Layer | Scenario | Contract pinned |
+|---|---|---|
+| Recorded journey | Multi-turn conversation | Recorded reasoning/text chunks, two input turns, retained history, token totals, and idle editor state |
+| Recorded journey | Todo plan | Real `todo_write` execution, result card, and persistent plan rendering |
+| Recorded journey | Bash terminal card | Real local executor output, description, exit status, and completed terminal card |
+| Recorded journey | Parallel filesystem reads | Two calls from one assistant message, real file contents, ordering, and separate completed cards |
+| Recorded journey | Code Mode | Real `run_code` worker execution, two `tool/code-dispatch` events, captured program output, and completed card |
+| Recorded journey | Dynamic workflow | Real workflow worker, phase lifecycle, replayed child session, structured return value, and completed card |
+| Recorded journey | Cordis dynamic toolchain | Real mount, Code Mode inspect, direct subagent, workflow child, unmount, and all production presenters |
+| Transient state | Streaming and pending advanced calls | In-flight reasoning/text plus pending Code Mode, workflow, and Cordis cards that disappear from completed logs |
+| Transient state | Cards, interaction, layout, failure, and shutdown | Collapsed/expanded card families, question validation, compaction replacement, resize reflow, help/errors, cursor restoration, and terminal stop |
+
+## Alternatives considered
+
+- **Snapshot raw terminal writes** — rejected because differential rendering may change write boundaries without changing the screen, while cursor and clear sequences are unreadable in review.
+- **Snapshot component render lines before terminal output** — rejected because it does not test ANSI parsing, cursor movement, overlays, viewport behavior, or independent components in one frame.
+- **Build every completed flow by appending session events** — rejected because a hand-authored event sequence can drift from the agent loop, tool execution, child-session binding, or worker behavior while its presentation test stays green. Direct event construction remains limited to transient renderer states.
+- **Reuse ACP stdout goldens as the TUI oracle** — rejected because a recorded model journey is transport-neutral but its presentation is not. TUI scenarios own terminal goldens while using the same JSONL replay vocabulary.
+- **Commit raster screenshots** — rejected because fonts, glyph metrics, antialiasing, and host terminal themes make them platform-sensitive and make semantic style changes difficult to review.
+- **Use only PTY end-to-end tests** — rejected because raw PTY output is a stream of historical drawing operations, not queryable final state. PTY tests retain the real Loader/input/teardown boundary, while the emulator owns broad state coverage.
+
+## Consequences
+
+- Completed advanced snapshots now fail when the real Code Mode, workflow, subagent, filesystem, bash, or Cordis path breaks, rather than accepting a fabricated result event.
+- TUI visual regressions produce readable cell-and-style diffs, while JSONL fixtures retain the exact model chunks that made the production path execute.
+- The emulator uses xterm's proposed buffer API. An xterm upgrade requires rerunning and reviewing the semantic projection; terminal-specific behavior still needs the PTY smoke.
+- Goldens deliberately encode wrapping and viewport behavior at fixed sizes. Intentional layout changes use keyless refresh, while model-journey changes use record mode and review both JSONL and terminal diffs.
diff --git a/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md
new file mode 100644
index 0000000000..d1c609c6ce
--- /dev/null
+++ b/docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md
@@ -0,0 +1,70 @@
+# RFC: TUI 语义终端状态快照
+
+Status: implemented
+
+[English](2026-07-18-tui-terminal-state-snapshots.md) | 中文
+
+## 问题
+
+TUI 是有状态的渲染器。用户最终看到的结果取决于 ANSI 解析、差分帧、换行、回滚缓冲、视口位置、终端宽度、焦点、光标状态，以及各工具的呈现意图。收集 `Terminal.write()` 片段的单元测试可以验证事件处理，却无法验证终端最终显示的画面。同一画面也可能由不同的写入片段产生，因此固定这些片段会制造误报。
+
+组件行快照止于 ANSI 进入终端之前，无法覆盖光标移动、清屏、样式、浮层组合和重排。栅格截图会带入与 TUI 契约无关的字体和平台渲染噪声。直接追加看似合理的会话事件来构造完整流程还存在另一处盲区：这种测试只能证明渲染器接受这些数据形态，无法证明生产环境的 agent loop（智能体循环）和工具实现会生成这些事件。
+
+因此，TUI 既需要确定、便于评审的终端状态表示，也需要通过已录制模型流程执行真实下游组件，并保留一项范围更小、覆盖真实进程与 PTY 边界的测试。
+
+## 决策
+
+TUI 覆盖分为四个互补层次：
+
+1. `packages/ui/tui/tests/tui.spec.ts` 直接测试事件映射、输入路由、资源释放和错误行为。
+2. `packages/ui/tui/tests/tui.snapshot.ts` 将生产 TUI 挂载到无界面终端模拟器，覆盖完整会话日志无法保留的瞬态：进行中的流式输出、待完成工具调用、浮层、展开状态、压缩重排、错误和关闭过程。
+3. `examples/tui-agent/tests/tui.snapshot.ts` 通过生产 agent loop 和真实工具回放已提交的 JSONL 会话日志，再比较生成的语义终端状态。
+4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 在 PTY 中启动真实 Loader 组合，驱动一段经过流式输出和 `ask_user_question` 的脚本化会话，并验证启动、输入、退出、失败报告和终端恢复。
+
+可运行 TUI 在 `examples/tui-agent` 中拥有独立叶节点，与 readline `coding-agent` 和 `acp-agent` 叶节点并列。它通过带断言的 include patch 复用 coding agent 的后端与工具组合，只把共享终端应用固定为 `ui.mode: tui`；TUI 快照和 PTY 测试也归属这个叶节点。
+
+### 已录制会话回放
+
+每个示例级场景目录都包含 `session.jsonl`、可选的子会话日志 `session.<n>.jsonl`，以及 `terminal.golden.txt`。主日志提供用户来源的 `user/message` 提示词和已录制的 `assistant/chunk` 序列。`dsh-llm-replay` 为每个会话派生一份模型调用脚本，并将子日志绑定到新建的子会话；这是测试中唯一的 mock 边界。agent loop、bash 与文件系统实现、Code Mode worker、subagent 提供方、工作流 worker、Cordis 工具、呈现器和 TUI 都使用生产实现。
+
+如果工具调用顺序不符、预期事件数量不足、工具结果报错、轮次以错误结束、工作流生命周期不完整，或者实时子会话数量与 fixture（测试前置数据）集合不一致，测试都会失败。即使终端金标表面正确，这些断言也能阻止失败或被绕过的生产路径混入结果。
+
+真实模型 fixture 通过 `DSH_SNAPSHOT=record` 更新；录制模式会重写其主会话与子会话 JSONL 日志以及终端金标。确定性的 Cordis 工具链保留一份人工编写的完整 JSONL 脚本，因为要求真实模型稳定经过五个指定工具边界和两个子会话并不是可靠的录制契约。`DSH_SNAPSHOT=refresh` 会无密钥回放所有已提交脚本，并且只重写派生的终端金标。普通回放只比较而不写入，未知模式值会快速失败。
+
+### 语义终端投影
+
+包内的 `HeadlessTerminal` 实现与进程终端相同的 pi-tui `Terminal` 接口，并把每次 ANSI 写入交给固定版本的 `@xterm/headless` 解析器。读取状态前，快照代码会等待同步帧稳定，因此每个检查点表示已经完成的画面，而不是依赖计时的写入前缀。
+
+每份金标把终端尺寸、活动缓冲区和视口坐标、生命周期与光标状态、各行、换行标记以及非默认样式区间投影为文本。滚动内容较多的卡片捕获已使用缓冲区；浮层捕获可见视口。文本和样式相互分离，评审人无需解码 ANSI 字节即可区分内容变化与呈现变化。
+
+每个检查点还会对完整终端状态强制执行主题无关性：禁止 RGB 颜色、禁止 ANSI 0–15 以外的调色板项，也禁止显式背景色。选择行使用终端默认色进行反显，因此仍然有效。两套测试都拥有封闭清单，会拒绝缺失的场景、缺失的检查点和遗留金标文件。
+
+### 必需场景矩阵
+
+| 层次 | 场景 | 固定的契约 |
+|---|---|---|
+| 已录制流程 | 多轮会话 | 已录制的推理与文本分片、两轮输入、保留历史、token 总量和空闲编辑器状态 |
+| 已录制流程 | Todo 计划 | 真实 `todo_write` 执行、结果卡片和持久计划渲染 |
+| 已录制流程 | Bash 终端卡片 | 真实本地执行器输出、说明、退出状态和已完成终端卡片 |
+| 已录制流程 | 并行文件读取 | 同一条 assistant 消息中的两次调用、真实文件内容、顺序和两个独立完成卡片 |
+| 已录制流程 | Code Mode | 真实 `run_code` worker 执行、两条 `tool/code-dispatch` 事件、捕获的程序输出和已完成卡片 |
+| 已录制流程 | 动态工作流 | 真实工作流 worker、阶段生命周期、回放的子会话、结构化返回值和已完成卡片 |
+| 已录制流程 | Cordis 动态工具链 | 真实挂载、Code Mode 检查、直接 subagent、工作流子会话、卸载和全部生产呈现器 |
+| 瞬态 | 流式输出与待完成高级调用 | 进行中的推理和文本，以及完整日志中不会保留的待完成 Code Mode、工作流和 Cordis 卡片 |
+| 瞬态 | 卡片、交互、布局、失败和关闭 | 折叠与展开的卡片族、问题校验、压缩替换、尺寸重排、帮助与错误、光标恢复和终端停止 |
+
+## 曾考虑的替代方案
+
+- **快照原始终端写入**：不予采纳，因为差分渲染可能在画面不变时改变写入边界，而且光标与清屏序列难以评审。
+- **快照进入终端输出之前的组件渲染行**：不予采纳，因为它无法测试 ANSI 解析、光标移动、浮层、视口行为，也无法测试独立组件在同一帧中的相互作用。
+- **通过追加会话事件构造所有完整流程**：不予采纳，因为人工编写的事件序列可能与 agent loop、工具执行、子会话绑定或 worker 行为发生偏差，但呈现测试仍然保持绿色。直接构造事件只用于渲染器瞬态。
+- **复用 ACP stdout 金标作为 TUI 判定依据**：不予采纳，因为已录制模型流程与传输方式无关，其呈现方式却并非如此。TUI 场景使用同一套 JSONL 回放词汇，但拥有独立的终端金标。
+- **提交栅格截图**：不予采纳，因为字体、字形度量、抗锯齿和宿主终端主题会使结果依赖平台，也会增加语义样式变更的评审难度。
+- **只使用 PTY 端到端测试**：不予采纳，因为原始 PTY 输出是一系列历史绘制操作，而不是可查询的最终状态。PTY 测试保留真实 Loader、输入与清理边界，模拟器负责广泛的状态覆盖。
+
+## 后果
+
+- 当真实 Code Mode、工作流、subagent、文件系统、bash 或 Cordis 路径损坏时，已完成高级快照会失败，不会继续接受伪造的结果事件。
+- TUI 视觉回归会产生便于阅读的单元格和样式 diff，而 JSONL fixture 会保留触发生产路径的确切模型分片。
+- 模拟器使用 xterm 的拟议缓冲区 API。升级 xterm 时必须重新运行并评审语义投影；终端特有行为仍需由 PTY 冒烟测试覆盖。
+- 金标有意固定指定尺寸下的换行与视口行为。预期布局变更使用无密钥刷新；模型流程变更使用录制模式，并同时评审 JSONL 与终端 diff。
diff --git a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.md b/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.md
deleted file mode 100644
index 2731d35448..0000000000
--- a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# RFC: Retire the standalone subagent mock package
-
-Status: proposed
-
-English | [中文](2026-07-19-retire-subagent-mock-package.zh.md)
-
-## Problem
-
-`@deepseek-ai/dsh-subagent-mock` is a configurable test double packaged as a workspace plugin. Its only external consumers are the `tool-subagent` unit suite and the tool-catalog generator. No runtime package, example, snapshot configuration, or real provider loads it.
-
-That narrow fixture carries a manifest, exports, peer and development dependencies, project references, package README obligations, Loader composition tests, module-graph membership, and documentation-gate exceptions. The tool-catalog generator mounts it only to make the real subagent tool register its schema; it never executes a child.
-
-## Proposal
-
-Delete `packages/support/subagent-mock`. Move the scripted provider behavior actually used by `tool-subagent` into a package-local test fixture while continuing to exercise the real `SubagentService`, provider registry, and tool implementation.
-
-Have the tool-catalog generator register the minimal provider descriptor required before mounting `ToolSubagent`. Remove the package references, manifest dependency, graph node, README allowlists, and mock-specific Loader tests.
-
-## Alternatives considered
-
-**Keep a reusable mock package for future tests.** Reuse has not materialized outside one test file and one generator. A future second consumer can extract a fixture once its shared contract is known; packaging all configurable reply, cancellation, result, and Loader behavior today makes test infrastructure look like a supported backend.
-
-**Generate the subagent schema without mounting the real tool.** Hand-constructing or importing the schema would weaken the catalog's check that the production registry and tool composition expose the documented shape. The generator should keep mounting the real service and tool with only the child boundary replaced.
-
-## Acceptance criteria
-
-- `packages/support/subagent-mock` and every workspace, graph, dependency, and documentation entry for it are removed.
-- `tool-subagent` tests retain every scripted reply, structured-result, cancellation, foreground/background, and task-integration case they currently exercise through the real service and tool.
-- Tool-catalog generation mounts the production subagent registry and tool with a minimal local provider and produces a byte-identical catalog.
-- No runtime or example package gains a dependency on test-only fixtures.
-- Focused subagent tests, catalog and graph generation, module-graph verification, build, hygiene, and the full pre-push suite pass.
-
-## Risks
-
-Relocating the fixture could accidentally replace too much production composition with a stub. The local fixture must implement only the nondeterministic child boundary; capability checks, lifecycle, task handling, and tool output remain under production code. Mock Loader and HMR coverage can disappear because no deployed composition consumes the package afterward.
diff --git a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.zh.md b/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.zh.md
deleted file mode 100644
index 919c565022..0000000000
--- a/docs/rfc/proposed/simplification/2026-07-19-retire-subagent-mock-package.zh.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# RFC: 撤销独立的 subagent mock 包
-
-Status: proposed
-
-[English](2026-07-19-retire-subagent-mock-package.md) | 中文
-
-## 问题
-
-`@deepseek-ai/dsh-subagent-mock` 是一个以工作区插件形式发布的可配置测试替身。它仅有两个外部消费方：`tool-subagent` 单元测试和工具目录生成器。运行时包、示例、快照配置和真实提供方都不会加载它。
-
-这个用途狭窄的 fixture（测试前置数据）需要维护 manifest（元数据清单）、导出、对等依赖（peer dependency）与开发依赖、项目引用、包（package）README 契约、Loader 组合测试、模块图成员关系以及文档门禁例外。工具目录生成器挂载它，只是为了让真实 subagent 工具注册 schema；生成器从不执行子 agent。
-
-## 提案
-
-删除 `packages/support/subagent-mock`。把 `tool-subagent` 实际使用的脚本化提供方行为移入该包的本地测试 fixture，同时继续测试真实的 `SubagentService`、提供方注册表和工具实现。
-
-工具目录生成器在挂载 `ToolSubagent` 前，只注册所需的最小提供方描述。删除该包的项目引用、manifest 依赖、图节点、README 允许列表和 mock 专用 Loader 测试。
-
-## 备选方案
-
-**为未来测试保留可复用 mock 包。** 除一个测试文件和一个生成器外，复用需求并未出现。未来产生第二个消费方时，可以在共享契约明确后再提取 fixture；当前把所有可配置回复、取消、结果与 Loader 行为打包，会使测试基础设施看起来像受支持的后端。
-
-**不挂载真实工具，直接生成 subagent schema。** 手工构造或直接导入 schema，会削弱目录生成器对生产注册表与工具组合是否公开文档结构的校验。生成器应继续挂载真实服务与工具，只替换不确定的子 agent 边界。
-
-## 验收标准
-
-- 删除 `packages/support/subagent-mock`，并移除其全部工作区、图、依赖和文档条目。
-- `tool-subagent` 测试保留当前通过真实服务与工具覆盖的全部脚本化回复、结构化结果、取消、前台与后台运行以及任务集成用例。
-- 工具目录生成器使用最小本地提供方挂载生产 subagent 注册表与工具，并生成字节级一致的目录。
-- 运行时包与示例包都不会新增对测试专用 fixture 的依赖。
-- 聚焦 subagent 测试、目录与图生成、模块图校验、构建、hygiene 和完整 pre-push 门禁全部通过。
-
-## 风险
-
-迁移 fixture 时，可能会误将过多生产组合替换成测试替身。本地 fixture 只能实现不确定的 subagent 边界；能力检查、生命周期、任务处理与工具输出仍由生产代码负责。由于之后不再有部署组合消费该包，可以删除 mock 的 Loader 与 HMR 覆盖。
diff --git a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.md b/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.md
deleted file mode 100644
index 0e4fa14b21..0000000000
--- a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# RFC: Use one surface manager per session
-
-Status: proposed
-
-English | [中文](2026-07-19-use-one-session-surface-manager.zh.md)
-
-## Problem
-
-`Session` maintains two `SurfaceManager` instances over the same append-only event log. `surfaceValidator` eagerly validates seed and append candidates, while the lazy `_surface` independently folds committed events for `session.surface`, derived messages, compaction, and workspace context. Once the public surface is read, every later event advances duplicate node and replacement-generation state.
-
-The [session surface decision](../../implemented/architecture/2026-06-18-session-surface.md) calls for one ordered surface and one representation to validate. The second manager does not create an independent authority or protect a different failure boundary; it repeats the canonical fold and gives the two views a state-drift opportunity.
-
-## Proposal
-
-Keep one `SurfaceManager` per `Session`. Seed and append acceptance continue to call `validateNext()` before committing an event, and the public surface view reads `nodes` and `replaceGeneration` from that same manager.
-
-Expose only the readonly surface contract from `Session.surface`; candidate validation remains owned by `Session`. Retain `foldSurface()` as the detached full-log replay function used by offline validation and reconstruction.
-
-## Implementation plan
-
-1. In `packages/core/session/src/surface.ts`, export a structural `SessionSurface` contract containing only readonly `nodes` and `replaceGeneration`, and make `SurfaceManager` implement it. Re-export that type from `packages/core/session/src/index.ts` so `Session.surface` no longer exposes `validateNext()` through its declaration.
-2. In `Session`, replace `surfaceValidator` and lazy `_surface` with one eagerly constructed `surfaceManager`. Route seed and append validation through that manager and return it from `get surface(): SessionSurface`; `deriveMessages()` will read the same nodes and generation. `validateNext()` may synchronize already committed log entries, but it must only plan the uncommitted candidate. The candidate reaches manager state after `log.push()` and the next delta synchronization, so rejection by surface validation or pre-commit `internal/dispatch` cannot leave phantom state.
-3. Keep `foldSurface()` and the transition functions in `surface.ts` unchanged. Compile and exercise the direct consumers in `packages/compact/compact/src/tool-pairing.ts`, `packages/compact/compact-basic/src/region.ts`, and `packages/context/workspace-context/src/state.ts`; they continue to consume only nodes and replacement generation.
-4. Extend `packages/core/session/tests/surface.spec.ts` to read the public view before an invalid candidate, prove that nodes and generation remain at the accepted prefix after rejection, append a later valid event, and compare every resulting prefix with `foldSurface()`. Add an `internal/dispatch` veto case and a type-level `SessionSurface` assertion in `session.spec.ts`, while retaining the seeded replay, delta-growth, replacement, generation, and derived-cache cases.
-5. Run the request-reconstruction, compaction tool-pairing, compaction range, and workspace-context regression suites that consume the surface. In the implementation PR, update `packages/core/session/README.md`, `docs/core-data-structures/session.md`, the implemented session-surface RFC and its Chinese counterpart, the translation record, `scripts/type-equiv.manifest.json`, and the generated RFC index before moving this RFC pair to `implemented/`.
-
-## Alternatives considered
-
-**Keep acceptance and projection state separate.** Separate instances appear to isolate public reads from validation, but ordinary callers already receive borrowed surface state and cannot mutate it through the declared readonly contract. A cast that mutates the returned node array already corrupts derived history; duplicating the manager is not a sound runtime trust boundary.
-
-**Recompute the public surface from the full log on every access.** This removes cached duplicate state but gives up incremental derivation and makes repeated request construction scale with complete session history.
-
-## Acceptance criteria
-
-- A live `Session` owns exactly one incremental `SurfaceManager`.
-- Seed and append candidates are validated before publication with no partial surface mutation on rejection.
-- `session.surface`, derived messages, compaction, and workspace context observe the same nodes and replacement generation as the acceptance path.
-- `foldSurface()` remains available for detached replay and agrees with the live manager for every accepted prefix.
-- Session surface, seed, request reconstruction, compaction tool-pairing, and workspace-context tests pass.
-
-## Risks
-
-Sharing one manager makes the readonly borrowed-state contract more important because a hostile cast could corrupt both validation and projection state. The implementation should return a narrowed view and keep mutation methods inaccessible through `Session.surface`; JavaScript callers that deliberately bypass the type contract remain outside the supported same-process boundary.
diff --git a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.zh.md b/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.zh.md
deleted file mode 100644
index 26126310ee..0000000000
--- a/docs/rfc/proposed/simplification/2026-07-19-use-one-session-surface-manager.zh.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# RFC: 每个会话只使用一个表层管理器
-
-Status: proposed
-
-[English](2026-07-19-use-one-session-surface-manager.md) | 中文
-
-## 问题
-
-`Session` 针对同一份仅追加事件日志维护两个 `SurfaceManager` 实例。`surfaceValidator` 主动校验种子事件与追加候选事件，延迟创建的 `_surface` 则独立折叠已提交事件，供 `session.surface`、派生消息、压缩（compaction）和工作区上下文使用。一旦读取公共表层，之后的每个事件都会推进两份重复的节点状态与替换代数状态。
-
-[会话表层决策](../../implemented/architecture/2026-06-18-session-surface.md)要求系统只保留一个有序表层，并使用一种表示完成校验。第二个管理器既不形成独立真源，也不保护不同的失败边界；它只会重复规范折叠，并使两个视图可能出现状态偏差。
-
-## 提案
-
-每个 `Session` 只保留一个 `SurfaceManager`。种子事件与追加事件的接纳流程仍在提交事件之前调用 `validateNext()`，公共表层视图则从同一个管理器读取 `nodes` 与 `replaceGeneration`。
-
-`Session.surface` 只公开只读表层契约，候选事件校验仍由 `Session` 负责。保留 `foldSurface()`，用于离线校验与重建时执行分离的完整日志回放。
-
-## 实施计划
-
-1. 在 `packages/core/session/src/surface.ts` 中，导出结构化的 `SessionSurface` 契约，只包含只读的 `nodes` 与 `replaceGeneration`，并让 `SurfaceManager` 实现该契约。从 `packages/core/session/src/index.ts` 重新导出这个类型，使 `Session.surface` 的声明不再暴露 `validateNext()`。
-2. 在 `Session` 中，用一个主动创建的 `surfaceManager` 替换 `surfaceValidator` 与延迟创建的 `_surface`。种子事件与追加事件都通过该管理器校验，`get surface(): SessionSurface` 返回同一个对象，`deriveMessages()` 也读取同一份节点与代数。`validateNext()` 可以同步已提交的日志事件，但对尚未提交的候选事件只能制定变更计划。候选事件在 `log.push()` 之后、下一次增量同步时才进入管理器状态，因此表层校验拒绝或提交前 `internal/dispatch` 否决都不会留下虚假状态。
-3. 保持 `foldSurface()` 与 `surface.ts` 中的状态转换函数不变。编译并验证 `packages/compact/compact/src/tool-pairing.ts`、`packages/compact/compact-basic/src/region.ts` 和 `packages/context/workspace-context/src/state.ts` 中的直接消费方；它们仍然只读取节点与替换代数。
-4. 扩展 `packages/core/session/tests/surface.spec.ts`：先读取公共视图，再提交无效候选事件，证明拒绝后节点与代数仍停留在已接纳前缀；随后追加有效事件，并把每个结果前缀与 `foldSurface()` 比较。在 `session.spec.ts` 中新增 `internal/dispatch` 否决用例与类型层面的 `SessionSurface` 断言，同时保留种子回放、增量增长、替换、代数和派生缓存用例。
-5. 运行消费表层的请求重建、压缩工具配对、压缩范围与工作区上下文回归套件。在实现 PR 中，先更新 `packages/core/session/README.md`、`docs/core-data-structures/session.md`、已实现会话表层 RFC 及其中文对应文件、翻译记录、`scripts/type-equiv.manifest.json` 和生成的 RFC 索引，再把本 RFC 双语文件移入 `implemented/`。
-
-## 备选方案
-
-**继续分离接纳状态与投影视图。** 两个独立实例看似能够隔离公共读取和校验，但普通调用方目前取得的就是借用的表层状态，无法通过声明的只读契约修改它。通过类型断言修改返回的节点数组，本就会破坏派生历史；复制管理器并不能构成可靠的运行时信任边界。
-
-**每次读取都根据完整日志重新计算公共表层。** 该方案不再缓存重复状态，但会放弃增量派生，使每次请求构造都随完整会话历史增长。
-
-## 验收标准
-
-- 每个活跃 `Session` 只拥有一个增量 `SurfaceManager`。
-- 种子事件与追加候选事件都在发布前完成校验，拒绝事件时不会留下只修改一半的表层状态。
-- `session.surface`、派生消息、压缩和工作区上下文观察到的节点与替换代数，和接纳路径使用的状态完全一致。
-- `foldSurface()` 仍可用于分离回放，并且对任意已接纳前缀都与活跃管理器一致。
-- 会话表层、种子、请求重建、压缩工具配对和工作区上下文测试全部通过。
-
-## 风险
-
-共享一个管理器会提高只读借用状态契约的重要性，因为恶意类型断言可能同时破坏校验状态和投影视图。实现应返回收窄后的视图，避免通过 `Session.surface` 暴露修改方法；刻意绕过类型契约的 JavaScript 调用方不属于受支持的同进程边界。
diff --git a/docs/rfc/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md b/docs/rfc/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
index 4c52d0b1a4..266a1d911d 100644
--- a/docs/rfc/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
+++ b/docs/rfc/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
@@ -1,19 +1,19 @@
 # RFC: Prune the unimplemented subagent seam vocabulary
 
-Status: rejected — the deferred capability vocabulary (`outputSchema`/`structured`, `toolFilter`, `sendMessage`/`resume`) is intentionally reserved surface: the seam advertises the full intended contract ahead of its implementations by design, so providers and consumers grow into a stable shape rather than re-negotiating it per capability. The consumer-evidence analysis below stands as the record of what is currently unimplemented.
+Status: rejected — the deferred capability vocabulary (`outputSchema`/`structured`, `toolFilter`, `sendMessage`/`resume`) is intentionally reserved surface: the seam advertises the full intended contract ahead of its implementations by design, so providers and consumers grow into a stable shape rather than re-negotiating it per capability. The consumer-evidence analysis below records the decision-time state.
 
 ## Problem
 
 The [subagent seam](../../implemented/feature/2026-06-21-subagent-capability-seam.md) shipped a two-tier capability design: start-time capability flags checked by the service, and optional runtime methods on `SubagentRun`. Three start-time features and both optional runtime methods have zero implementations and zero callers:
 
-- **`outputSchema`/`structured` and `toolFilter`** (`SubagentCapabilities`, `SubagentStartRequest`, `SubagentResult` in `packages/subagent/subagent/src/types.ts`): every real provider declares `outputSchema: false, toolFilter: false` (`packages/subagent/subagent-spawn/src/index.ts`, `packages/subagent/subagent-fork/src/index.ts`, `packages/subagent/subagent-acp/src/index.ts`); the sole production `ctx.subagents.start` caller (`packages/subagent/tool-subagent/src/index.ts`) builds `{ prompt, parent, signal?, agentOptions? }` and structurally cannot set either; `structured` is produced only by the test mock (`packages/support/subagent-mock`) for its own spec. The service's capability check carries two assert rows whose only exercisers are the rejection tests.
+- **`outputSchema`/`structured` and `toolFilter`** (`SubagentCapabilities`, `SubagentStartRequest`, `SubagentResult` in `packages/subagent/subagent/src/types.ts`): at the decision point, every real provider declared `outputSchema: false, toolFilter: false` (`packages/subagent/subagent-spawn/src/index.ts`, `packages/subagent/subagent-fork/src/index.ts`, `packages/subagent/subagent-acp/src/index.ts`); the sole production `ctx.subagents.start` caller (`packages/subagent/tool-subagent/src/index.ts`) built `{ prompt, parent, signal?, agentOptions? }` and structurally could not set either; `structured` appeared only in the scripted test fixture. The service's capability check carried two assert rows whose only exercisers were the rejection tests.
 - **`SubagentRun.sendMessage` / `SubagentRun.resume`** (same file): implemented by NO provider — not even the mock; the spawn spec asserts their *absence*.
 
 The only reason `dsh-subagent` depends on `dsh-tools` at all is `outputSchema`'s `SchemaSpec` type. Three subsequent subagent workstreams (per-session snapshot replay, the fork seed boundary, the ACP backend) landed around this surface without growing a single consumer.
 
 ## Proposal
 
-Remove `outputSchema`/`structured`, `toolFilter`, `sendMessage`, and `resume` from the seam; shrink `SubagentCapabilities` to `{ depthLimit }`; drop the two capability-assert rows, the all-false flags on the three providers, the mock's structured branch and its `capabilities`/`structured` config knobs, and the tests that exist to pin the removed surface (the two rejection rows, the spawn absence test, the mock structured specs). Drop the `dsh-tools` peer/dev dependency from `packages/subagent/subagent/package.json`. Update the [subagent.md](../../../core-data-structures/subagent.md) pastes and the type-equiv manifest, and the README rows in `packages/subagent/subagent`, `packages/subagent/subagent-spawn`, `packages/subagent/subagent-fork`, and `packages/support/subagent-mock`. The implementing PR amends the seam RFC's capability catalog per [implemented/AGENTS.md](../../implemented/AGENTS.md).
+Remove `outputSchema`/`structured`, `toolFilter`, `sendMessage`, and `resume` from the seam; shrink `SubagentCapabilities` to `{ depthLimit }`; drop the two capability-assert rows, the all-false flags on the three providers, the scripted fixture's structured branch and capability knobs, and the tests that exist to pin the removed surface. Drop the `dsh-tools` peer/dev dependency from `packages/subagent/subagent/package.json`. Update the [subagent.md](../../../core-data-structures/subagent.md) pastes and the type-equiv manifest, plus the affected provider READMEs. The implementing PR amends the seam RFC's capability catalog per [implemented/AGENTS.md](../../implemented/AGENTS.md).
 
 **Keep** `depthLimit`/`maxDepth` and capability checks. The in-process backend enforces the limit, although the shipping tool does not yet set it. Recursion is a known seam risk, so the appropriate follow-up is to supply a tool default rather than delete working enforcement.
 
diff --git a/docs/testing.md b/docs/testing.md
index 06d8fd4321..ab34b0af51 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -7,7 +7,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`).
 - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped.
 - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e RFC](rfc/implemented/testing/2026-06-19-real-api-e2e-ci.md)).
-- **Snapshot** (`pnpm run test:snapshot`): boots the real example subprocess, replays a recorded session keyless, diffs normalized stdout + the re-persisted log against committed goldens ([snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). Use `pnpm run test:snapshot:record` when the model transcript should change; use `pnpm run test:snapshot:refresh` when the committed transcript is still the right mock LLM input and replay goldens need keyless rewrite. Review the golden diff. System-prompt/tool-schema content is pinned by ONE scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Snapshot** (`pnpm run test:snapshot`): transport-specific keyless goldens cover external presentation. ACP suites boot the real example subprocess, replay a recorded session, and diff normalized stdout plus the re-persisted log ([ACP snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). TUI completed journeys replay recorded primary/child JSONL through the real agent loop and tools before projecting ANSI into semantic terminal-state goldens; package-local snapshots retain transient renderer states, and a real PTY conversation covers the process boundary ([TUI snapshot RFC](rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript must change and `pnpm run test:snapshot:refresh` when committed replay input remains correct; review every JSONL and golden diff. System-prompt/tool-schema content is pinned by ONE ACP scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 
 ## The with-key policy: inference is cheap here
 
@@ -35,4 +35,4 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 ## When a snapshot test is required
 
-Any change affecting the editor-facing transcript or end-to-end agent UX — the ACP bridge, the loop's observable output, tool presentation — adds or updates a scenario in the owning example's snapshot suite (`examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory; `examples/acp-agent` is the primary suite), or states in the PR why none applies. New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
+Any change affecting an editor-facing transcript or end-to-end agent UX adds or updates a scenario in the owning snapshot suite, or states in the PR why none applies. ACP surfaces use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary). Completed interactive-terminal journeys use JSONL-driven scenarios under `examples/tui-agent/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
diff --git a/examples/README.md b/examples/README.md
index 5db1e18372..03b798e164 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -15,12 +15,18 @@ Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigge
 
 ## coding-agent
 
-A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-demo` app. The UI is a terminal readline REPL.
+A coding-agent REPL: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the `@deepseek-ai/dsh-stdio-demo` app's readline front door.
 
 Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
 
 Run the Code Mode overlay with `pnpm run demo:code-mode`, or pass `acp` for the ACP example. See the [Code Mode example](coding-agent/README.md#code-mode) for its composition and a sample task.
 
+## tui-agent
+
+The full-screen terminal sibling of `coding-agent`: it reuses the same coding backends and tools while forcing the shared terminal app to `dsh-tui`. It is the home of TUI PTY and snapshot scenarios.
+
+Run with: `pnpm run demo:tui` (needs `DEEPSEEK_API_KEY`). See [tui-agent/README.md](tui-agent/README.md) for controls and composition.
+
 ## cordis-agent
 
 The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. The `ctx.fs`/`ctx.web` services ride along provider-only, as the capabilities those plugins build on.
diff --git a/examples/coding-agent/README.md b/examples/coding-agent/README.md
index 9e627324d4..40e8b7087f 100644
--- a/examples/coding-agent/README.md
+++ b/examples/coding-agent/README.md
@@ -1,6 +1,6 @@
 # coding-agent
 
-The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + stdio chat + JSONL persistence, loaded from `cordis.yml`. The UI is a terminal readline REPL.
+The coding-agent REPL wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + readline chat + JSONL persistence, loaded from `cordis.yml`. The sibling [`tui-agent`](../tui-agent/README.md) fixes the same agent composition to the full-screen terminal front door.
 
 ## Run it
 
@@ -11,15 +11,9 @@ The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem t
 pnpm run demo:repl
 ```
 
-Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
+Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write`.
 
-```
-> fix the failing test in /path/to/project
-[main turn 1] (reasoning…)
-  [tool call] bash({"command": "node --test", "workdir": "/path/to/project"})
-  [tool result] … [exit code: 1]
-  …
-```
+The REPL renders reasoning, tool calls/results, and the latest todo list as line-oriented output suitable for terminals and pipes. Use `pnpm run demo:tui` for the interactive Markdown/card interface.
 
 ### Resuming a prior session
 
@@ -29,7 +23,7 @@ Each run starts a fresh session by default (its event log lands under `./.sessio
 RESUME_SESSION_ID=<prior-session-id> pnpm run demo:repl
 ```
 
-The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent.
+The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing or unreadable id starts no agent and emits `agent-loop/config-start-failed`: the TUI prints the failure and exits nonzero, while readline reports any dropped queued input and allows piped EOF to finish. Unset it or choose an existing session id.
 
 ## Code Mode
 
@@ -48,17 +42,17 @@ and watch the transcript: one `run_code` call, a program looping over tools, and
 
 ## What each leaf entry demonstrates
 
-This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (console logger, JSONL persistence, readline UI, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app and the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle it loads; the leaf wires the backends and model-facing optional tools:
+This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (JSONL persistence, the selected terminal channel, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app and the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle it loads; the leaf wires the backends and model-facing optional tools:
 
 | Entry | Demonstrates |
 |---|---|
 | `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes |
 | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
 | `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and generic `task_*` controls (`tool-tasks`) come from `dsh-agent-spine-demo`, so only the executor is a leaf choice |
-| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
+| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + JSONL persistence + the configured terminal channel + a pre-created `main` agent. This leaf fixes `ui.mode` to `readline`; `tui-agent` owns the corresponding TUI leaf |
 | `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
 | `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
-| `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a checklist in stdio |
+| `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a persistent TUI plan or readline checklist |
 | `fs-local`, `fs-policy`, `tool-fs` | the filesystem stack: the local `ctx.fs` provider, the read-before-write/edit policy gate (on the `fs/*` event gate), and the model-facing `read`/`write`/`edit` tools. Relative paths resolve against the session workspace |
 
 ## End-to-end tests (`pnpm run test:e2e`, key-gated)
diff --git a/examples/coding-agent/code-mode.cordis.yml b/examples/coding-agent/code-mode.cordis.yml
index 3fec40e0f3..b1f62829bc 100644
--- a/examples/coding-agent/code-mode.cordis.yml
+++ b/examples/coding-agent/code-mode.cordis.yml
@@ -20,6 +20,8 @@
           tools:
             mode: code
           welcome: 'code-mode agent ready. Give it a multi-tool task.'
+          ui:
+            mode: readline
           persona: |
             You are coding-agent, a coding assistant powered by the {{model}} model.
 
diff --git a/examples/coding-agent/composition.md b/examples/coding-agent/composition.md
index cc71975961..2956291dc8 100644
--- a/examples/coding-agent/composition.md
+++ b/examples/coding-agent/composition.md
@@ -3,7 +3,7 @@
 
 # Coding Agent App Composition
 
-The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.
+The coding-agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.
 
 ```mermaid
 flowchart LR
@@ -18,7 +18,7 @@ flowchart LR
   cfg --> plugin_coding_stdio_agent
   plugin_coding_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
   plugin_coding_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
-  plugin_coding_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  plugin_coding_stdio_agent --> frontdoor_stdio["@deepseek-ai/dsh-stdio<br/>pre-created main agent"]
   bundle_agent_core --> spine_llm["ctx.llm"]
   bundle_agent_core --> spine_sessions["ctx.sessions"]
   bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml
index bc3b542592..497e2a80c8 100644
--- a/examples/coding-agent/cordis.yml
+++ b/examples/coding-agent/cordis.yml
@@ -1,6 +1,6 @@
-# REPL agent with swappable DeepSeek and local-bash backends. `dsh-stdio-demo`
-# supplies the agent spine, workspace instructions, generic task controls,
-# logging, JSONL persistence, readline UI, and `main` agent.
+# Readline coding REPL with swappable DeepSeek and local-bash backends.
+# `dsh-stdio-demo` supplies the agent spine, workspace instructions, generic
+# task controls, JSONL persistence, the line-oriented front door, and `main`.
 # HMR remains a leaf because it requires Loader internals; `demo:repl` passes
 # `--expose-internals`. The app bin loads the gitignored root `.env`; this file
 # reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`.
@@ -37,6 +37,8 @@
     workspaceContext:
       maxBytes: 65536
     welcome: 'agent REPL ready. Give it a coding task.'
+    ui:
+      mode: readline
     # Keep the persona to identity and behavior; tool plugins own tool guidance.
     # The loop resolves {{model}} from this agent's configuration.
     persona: |
diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md
index 6a08c379fc..499379482f 100644
--- a/examples/cordis-agent/composition.md
+++ b/examples/cordis-agent/composition.md
@@ -24,7 +24,7 @@ flowchart LR
   cfg --> plugin_cordis_stdio_agent
   plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
   plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
-  plugin_cordis_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  plugin_cordis_stdio_agent --> frontdoor_stdio["dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent"]
   bundle_agent_core --> spine_llm["ctx.llm"]
   bundle_agent_core --> spine_sessions["ctx.sessions"]
   bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
diff --git a/examples/echo-agent/README.md b/examples/echo-agent/README.md
index d6156130db..183268f5da 100644
--- a/examples/echo-agent/README.md
+++ b/examples/echo-agent/README.md
@@ -4,7 +4,7 @@ Runnable demo: stdin chat with a scripted mock model and an echo tool. The all-m
 
 ## What it shows
 
-This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app (which bundles the whole [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) spine, the console logger, JSONL persistence, the readline UI, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`:
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app (which bundles the whole [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) spine, JSONL persistence, the TTY-selected `dsh-tui`/`dsh-stdio` front doors, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`:
 
 - `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the `echo` tool when the user types "echo <something>". Registered with `ctx.llm.registerAdapter(['mock-echo'], …)`.
 - `echo-tool.ts` — a tool registered via `ctx.tools.register(defineTool(…))` with typed `execute` args; echoes text back uppercased.
diff --git a/examples/echo-agent/composition.md b/examples/echo-agent/composition.md
index 9c9f04cb50..15f8e078fb 100644
--- a/examples/echo-agent/composition.md
+++ b/examples/echo-agent/composition.md
@@ -22,7 +22,7 @@ flowchart LR
   cfg --> plugin_echo_stdio_agent
   plugin_echo_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
   plugin_echo_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
-  plugin_echo_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  plugin_echo_stdio_agent --> frontdoor_stdio["dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent"]
   bundle_agent_core --> spine_llm["ctx.llm"]
   bundle_agent_core --> spine_sessions["ctx.sessions"]
   bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
diff --git a/examples/echo-agent/cordis.yml b/examples/echo-agent/cordis.yml
index 429ca118d6..6b3d19839b 100644
--- a/examples/echo-agent/cordis.yml
+++ b/examples/echo-agent/cordis.yml
@@ -29,7 +29,8 @@
   config:
     cwd: !!js process.cwd()
 
-# The app pre-creates `main` on the mock model and supplies logging, persistence, and readline UI.
+# The app pre-creates `main` on the mock model and supplies persistence plus
+# TTY-selected `dsh-tui`/`dsh-stdio` front doors; readline mode also owns logging.
 - id: stdio-agent
   name: '@deepseek-ai/dsh-stdio-demo'
   config:
diff --git a/examples/tui-agent/README.md b/examples/tui-agent/README.md
new file mode 100644
index 0000000000..ee5b610d53
--- /dev/null
+++ b/examples/tui-agent/README.md
@@ -0,0 +1,23 @@
+# tui-agent
+
+The full-screen terminal counterpart to the [`coding-agent`](../coding-agent/README.md) readline REPL and [`acp-agent`](../acp-agent/README.md) server. It reuses the coding agent's backends and tool composition, then fixes the shared terminal app to the `dsh-tui` front door.
+
+## Run it
+
+```sh
+pnpm run demo:tui
+```
+
+The command needs `DEEPSEEK_API_KEY` in the environment or the gitignored repository-root `.env`. Set `RESUME_SESSION_ID` to reopen a persisted conversation under `./.sessions`.
+
+The TUI renders Markdown history, reasoning, tool-owned terminal/diff/generic cards, token totals, and the latest todo list. Enter submits or steers while the agent is running; Ctrl+O expands cards, Ctrl+R toggles reasoning, Escape cancels, and `/help` lists commands. `ask_user_question` opens a keyboard-driven overlay.
+
+Run `pnpm run demo:code-mode tui` for the sibling Code Mode overlay.
+
+## Composition
+
+[`cordis.yml`](cordis.yml) includes the readline coding-agent leaf so the LLM, bash, filesystem, compaction, subagent, workflow, todo, timeout, and spill choices have one owner. Its asserted patch replaces only the terminal app config and forces `ui.mode: tui`; [`code-mode.cordis.yml`](code-mode.cordis.yml) applies the same front-door patch to the coding agent's Code Mode overlay.
+
+## Snapshot tests
+
+`tests/snapshots/<scenario>/session.jsonl` supplies recorded user prompts and model chunks; sibling child logs drive subagents and workflows. The keyless suite executes those scripts through the real loop and tool implementations, then compares readable terminal cell/style goldens. Use `pnpm run test:snapshot:refresh` for presentation-only changes and `pnpm run test:snapshot:record` with a DeepSeek key when a recorded model journey changes. The implemented [TUI snapshot RFC](../../docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns the scenario matrix and the split between recorded journeys, transient package snapshots, and PTY coverage.
diff --git a/examples/tui-agent/code-mode.cordis.yml b/examples/tui-agent/code-mode.cordis.yml
new file mode 100644
index 0000000000..7bb7932ba0
--- /dev/null
+++ b/examples/tui-agent/code-mode.cordis.yml
@@ -0,0 +1,30 @@
+# Code Mode keeps the TUI front door while reusing the coding-agent overlay's
+# worker runtime and one-tool registry composition.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ../coding-agent/code-mode.cordis.yml
+    patches:
+      - id: stdio-agent
+        name: '@deepseek-ai/dsh-stdio-demo'
+        config:
+          provider: deepseek
+          model: deepseek-v4-flash
+          resumeSessionId: !!js process.env.RESUME_SESSION_ID
+          persistenceRoot: './.sessions'
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: code
+          welcome: 'TUI Code Mode ready. Give it a multi-tool task.'
+          ui:
+            mode: tui
+            tui:
+              showReasoning: true
+              maxToolOutputLines: 12
+          persona: |
+            You are coding-agent, a coding assistant powered by the {{model}} model.
+
+            You work by writing TypeScript programs for run_code: batch related
+            tool work into one program, loop and branch where it helps, and print
+            or return ONLY the findings that matter.
diff --git a/examples/tui-agent/composition.md b/examples/tui-agent/composition.md
new file mode 100644
index 0000000000..511f76d41e
--- /dev/null
+++ b/examples/tui-agent/composition.md
@@ -0,0 +1,28 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# TUI Agent App Composition
+
+The TUI agent reuses the coding-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.
+
+```mermaid
+flowchart LR
+  cfg["examples/tui-agent<br/>cordis.yml"]
+  plugin_tui_base["base<br/>@deepseek-ai/dsh-stdio-demo"]
+  cfg --> plugin_tui_base
+  plugin_tui_base --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
+  plugin_tui_base --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_tui_base --> frontdoor_stdio["@deepseek-ai/dsh-tui<br/>pre-created main agent"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `base` | `@deepseek-ai/dsh-stdio-demo` |
+
+Source config: [`examples/tui-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
diff --git a/examples/tui-agent/cordis.yml b/examples/tui-agent/cordis.yml
new file mode 100644
index 0000000000..0f329c38e2
--- /dev/null
+++ b/examples/tui-agent/cordis.yml
@@ -0,0 +1,28 @@
+# Full-screen TUI front door over the same coding-agent composition used by the
+# readline REPL. The include keeps backends and optional tools aligned; the
+# patch owns only the terminal-specific app config.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ../coding-agent/cordis.yml
+    patches:
+      - id: stdio-agent
+        name: '@deepseek-ai/dsh-stdio-demo'
+        config:
+          provider: deepseek
+          model: deepseek-v4-flash
+          resumeSessionId: !!js process.env.RESUME_SESSION_ID
+          persistenceRoot: './.sessions'
+          workspaceContext:
+            maxBytes: 65536
+          welcome: 'TUI agent ready. Give it a coding task.'
+          ui:
+            mode: tui
+            tui:
+              showReasoning: true
+              maxToolOutputLines: 12
+          persona: |
+            You are coding-agent, a coding assistant powered by the {{model}} model.
+
+            Verify your work by running the code or tests. Keep answers brief and
+            factual.
diff --git a/examples/tui-agent/package.json b/examples/tui-agent/package.json
new file mode 100644
index 0000000000..f45e6746a3
--- /dev/null
+++ b/examples/tui-agent/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "tui-agent-example",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Runnable demo: the coding agent through the full-screen terminal UI"
+}
diff --git a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
new file mode 100644
index 0000000000..c55b3d355c
--- /dev/null
+++ b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
@@ -0,0 +1,61 @@
+import type { Context } from 'cordis'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+
+const CONTROL_PROBE = '\u001b]2;MODEL_CONTROLLED\u0007\u001b[999CMODEL_CURSOR\u009b31mMODEL_C1'
+const INITIAL_TEXT = `I need one decision before I continue. ${CONTROL_PROBE}`
+const FINAL_TEXT = 'Decision received. Scripted TUI run complete.'
+
+function textChunks(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    ...Array.from(text, (char): StreamChunk => ({ type: 'text-delta', index: 0, text: char })),
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'usage', usage: { inputTokens: 20, outputTokens: text.length } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+/** Keyless two-step adapter for the real-PTY TUI conversation test. */
+class ScriptedTuiAdapter extends LlmAdapter {
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const hasToolResult = options.messages.at(-1)?.content.some(block => block.type === 'tool-result') ?? false
+    if (hasToolResult) {
+      for (const chunk of textChunks(FINAL_TEXT)) yield chunk
+      return
+    }
+
+    const args = JSON.stringify({
+      questions: [{
+        id: 'mode',
+        header: 'Execution mode',
+        question: 'How should the scripted run proceed?',
+        options: [
+          { label: 'Safe', description: 'Use the guarded path.' },
+          { label: 'Fast', description: 'Use the shorter path.' },
+        ],
+      }],
+    })
+    const callId = CallId('call-ask-mode')
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    for (const char of INITIAL_TEXT) yield { type: 'text-delta', index: 0, text: char }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: INITIAL_TEXT } }
+    yield { type: 'block-start', index: 1, blockType: 'tool-call' }
+    yield { type: 'tool-call-delta', index: 1, id: callId, name: 'ask_user_question', argumentsDelta: args }
+    yield {
+      type: 'block-end',
+      index: 1,
+      block: { type: 'tool-call', id: callId, name: 'ask_user_question', arguments: args },
+    }
+    yield { type: 'usage', usage: { inputTokens: 20, outputTokens: 10 } }
+    yield { type: 'finish', reason: { kind: 'tool-calls' } }
+  }
+}
+
+export const name = 'tui-scripted-llm'
+export const inject = ['llm']
+
+/** Register the network-free adapter used by the PTY fixture. */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['tui-scripted'], new ScriptedTuiAdapter())
+}
diff --git a/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml
new file mode 100644
index 0000000000..e40405524e
--- /dev/null
+++ b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml
@@ -0,0 +1,27 @@
+# Real Loader composition for the keyless conversational PTY test. The app
+# bundle supplies the production agent/TUI/user-question stack; only the model
+# is scripted so the terminal interaction is deterministic and network-free.
+- id: scripted-llm
+  name: './tui-scripted-llm.ts'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-demo'
+  config:
+    provider: tui-scripted
+    model: tui-scripted-model
+    persistenceRoot: './.sessions'
+    workspaceContext:
+      maxBytes: 65536
+    welcome: 'scripted TUI ready.'
+    ui:
+      mode: tui
+      tui:
+        showReasoning: true
diff --git a/examples/tui-agent/tests/snapshots/bash-terminal-card/session.jsonl b/examples/tui-agent/tests/snapshots/bash-terminal-card/session.jsonl
new file mode 100644
index 0000000000..e53f4b3da3
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/bash-terminal-card/session.jsonl
@@ -0,0 +1,98 @@
+{"type":"session","version":0,"id":"e128dda9-ed11-4868-8266-0ef90d03c3d6","createdAt":1783352050748,"cwd":"/tmp/acp-snap-cwd-mrFUuk"}
+{"type":"turn/start","seq":0,"time":1783352050753,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783352050753,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783352050755,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783352050756,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783352051421,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783352051422,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783352051590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783352051618,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783352051618,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783352051619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783352051619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
+{"type":"assistant/chunk","seq":11,"time":1783352051619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":12,"time":1783352051645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" simple"}}}
+{"type":"assistant/chunk","seq":13,"time":1783352051675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":14,"time":1783352051675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":15,"time":1783352051675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":16,"time":1783352051676,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
+{"type":"assistant/chunk","seq":17,"time":1783352051676,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":18,"time":1783352051703,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":19,"time":1783352051704,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":20,"time":1783352051704,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":21,"time":1783352051704,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":22,"time":1783352051704,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":23,"time":1783352051790,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":24,"time":1783352051791,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":25,"time":1783352051820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":26,"time":1783352051820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":27,"time":1783352051820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"command"}}}
+{"type":"assistant/chunk","seq":28,"time":1783352051820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":29,"time":1783352051820,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":30,"time":1783352051848,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":31,"time":1783352051848,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":32,"time":1783352051848,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" TER"}}}
+{"type":"assistant/chunk","seq":33,"time":1783352051848,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"MIN"}}}
+{"type":"assistant/chunk","seq":34,"time":1783352051877,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"AL"}}}
+{"type":"assistant/chunk","seq":35,"time":1783352051877,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"_OK"}}}
+{"type":"assistant/chunk","seq":36,"time":1783352051877,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":37,"time":1783352051905,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":", "}}}
+{"type":"assistant/chunk","seq":38,"time":1783352051906,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":39,"time":1783352051906,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"description"}}}
+{"type":"assistant/chunk","seq":40,"time":1783352051935,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":41,"time":1783352051935,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":42,"time":1783352051935,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":43,"time":1783352051935,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"E"}}}
+{"type":"assistant/chunk","seq":44,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"cho"}}}
+{"type":"assistant/chunk","seq":45,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" TER"}}}
+{"type":"assistant/chunk","seq":46,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"MIN"}}}
+{"type":"assistant/chunk","seq":47,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"AL"}}}
+{"type":"assistant/chunk","seq":48,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"_OK"}}}
+{"type":"assistant/chunk","seq":49,"time":1783352051967,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" to"}}}
+{"type":"assistant/chunk","seq":50,"time":1783352052041,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" verify"}}}
+{"type":"assistant/chunk","seq":51,"time":1783352052041,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" terminal"}}}
+{"type":"assistant/chunk","seq":52,"time":1783352052041,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":" access"}}}
+{"type":"assistant/chunk","seq":53,"time":1783352052054,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":54,"time":1783352052054,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":55,"time":1783352052117,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."}}}}
+{"type":"assistant/chunk","seq":56,"time":1783352052118,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\"}"}}}}
+{"type":"assistant/chunk","seq":57,"time":1783352052118,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18}}}}
+{"type":"assistant/chunk","seq":58,"time":1783352052118,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":59,"time":1783352052121,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58],"surfaceOp":"append"}
+{"type":"tool/call","seq":60,"time":1783352052121,"data":{"turn":1,"step":1,"callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\"}"}}
+{"type":"tool/result","seq":61,"time":1783352052136,"data":{"turn":1,"step":1,"callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","content":[{"type":"text","text":"TERMINAL_OK\n"}],"isError":false},"sourceEventSeqs":[60],"surfaceOp":"append"}
+{"type":"step/end","seq":62,"time":1783352052137,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":63,"time":1783352052137,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":64,"time":1783352052701,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":65,"time":1783352052702,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":66,"time":1783352052780,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":67,"time":1783352052809,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" ran"}}}
+{"type":"assistant/chunk","seq":68,"time":1783352052838,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}}
+{"type":"assistant/chunk","seq":69,"time":1783352052838,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":70,"time":1783352052838,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":71,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":72,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"TER"}}}
+{"type":"assistant/chunk","seq":73,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"MIN"}}}
+{"type":"assistant/chunk","seq":74,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"AL"}}}
+{"type":"assistant/chunk","seq":75,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}}
+{"type":"assistant/chunk","seq":76,"time":1783352052867,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":77,"time":1783352052895,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":78,"time":1783352052896,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" should"}}}
+{"type":"assistant/chunk","seq":79,"time":1783352052924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" now"}}}
+{"type":"assistant/chunk","seq":80,"time":1783352052925,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":81,"time":1783352052925,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":82,"time":1783352052925,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}}
+{"type":"assistant/chunk","seq":83,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":84,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":85,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":86,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":87,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":88,"time":1783352052957,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
+{"type":"assistant/chunk","seq":89,"time":1783352052986,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":90,"time":1783352052986,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."}}}}
+{"type":"assistant/chunk","seq":91,"time":1783352052986,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":92,"time":1783352052986,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22}}}}
+{"type":"assistant/chunk","seq":93,"time":1783352052986,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":94,"time":1783352052987,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."},{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22}},"sourceEventSeqs":[64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93],"surfaceOp":"append"}
+{"type":"step/end","seq":95,"time":1783352052987,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":96,"time":1783352052987,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/bash-terminal-card/terminal.golden.txt b/examples/tui-agent/tests/snapshots/bash-terminal-card/terminal.golden.txt
new file mode 100644
index 0000000000..29ea17fd66
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/bash-terminal-card/terminal.golden.txt
@@ -0,0 +1,73 @@
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=27 bufferRow=27
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: bash-terminal-card                                                              │"
+  style 0-0 fg=bright-blue
+  style 2-36 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+12| " The user wants me to run a simple bash command and then reply with \"DONE\".                         "
+  style 1-74 fg=bright-black italic
+13| <blank>
+14| "▌ "
+  style 0-0 fg=green
+15| "▌ ✓ echo TERMINAL_OK                                                                                "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-19 bold
+16| "▌ Echo TERMINAL_OK to verify terminal access                                                        "
+  style 0-0 fg=green
+  style 2-43 fg=bright-black
+17| "▌ TERMINAL_OK                                                                                       "
+  style 0-0 fg=green
+18| "▌ [exit 0]                                                                                          "
+  style 0-0 fg=green
+  style 2-9 dim
+19| "▌ "
+  style 0-0 fg=green
+20| <blank>
+21| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+22| " The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\".        "
+  style 1-91 fg=bright-black italic
+23| <blank>
+24| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+25| " DONE                                                                                               "
+26| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+27| "                                                                                                    "
+  style 1-1 inverse
+28| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+29| "/workspace/project  ↑3.0k ↓115        idle  reasoning:on  tools:compact"
+  style 0-58 dim
+  style 67-99 dim
+30-35| <blank>
diff --git a/examples/tui-agent/tests/snapshots/code-mode/session.jsonl b/examples/tui-agent/tests/snapshots/code-mode/session.jsonl
new file mode 100644
index 0000000000..0fe57055e8
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/code-mode/session.jsonl
@@ -0,0 +1,150 @@
+{"type":"session","version":0,"id":"94cd1ae4-e1d1-4ec8-9d27-50a1f849b6b3","createdAt":1783611771392,"cwd":"/var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-BteTVR"}
+{"type":"turn/start","seq":0,"time":1783611771394,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783611771394,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783611771396,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783611771396,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783611771978,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783611772007,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783611772008,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":9,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}}
+{"type":"assistant/chunk","seq":10,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
+{"type":"assistant/chunk","seq":11,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
+{"type":"assistant/chunk","seq":12,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
+{"type":"assistant/chunk","seq":13,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":14,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" calls"}}}
+{"type":"assistant/chunk","seq":15,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":16,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}}
+{"type":"assistant/chunk","seq":17,"time":1783611772096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
+{"type":"assistant/chunk","seq":18,"time":1783611772124,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
+{"type":"assistant/chunk","seq":19,"time":1783611772153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}}
+{"type":"assistant/chunk","seq":20,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":21,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}}
+{"type":"assistant/chunk","seq":22,"time":1783611772211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}}
+{"type":"assistant/chunk","seq":23,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":24,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":25,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":26,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}}
+{"type":"assistant/chunk","seq":27,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}}
+{"type":"assistant/chunk","seq":28,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":29,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}}
+{"type":"assistant/chunk","seq":30,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":31,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":32,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}}
+{"type":"assistant/chunk","seq":33,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":34,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":35,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":36,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":37,"time":1783611772362,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":38,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"code"}}}
+{"type":"assistant/chunk","seq":39,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":40,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":41,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":42,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":43,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":44,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":45,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":46,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":47,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":48,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":49,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":50,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":51,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":52,"time":1783611772478,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":53,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":54,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":55,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":56,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_"}}}
+{"type":"assistant/chunk","seq":57,"time":1783611772508,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ONE"}}}
+{"type":"assistant/chunk","seq":58,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":59,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":60,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":61,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":62,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"First"}}}
+{"type":"assistant/chunk","seq":63,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
+{"type":"assistant/chunk","seq":64,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":65,"time":1783611772566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
+{"type":"assistant/chunk","seq":66,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":67,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":68,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":69,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":70,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":71,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":72,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":73,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":74,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":75,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":76,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":77,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":78,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":79,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":80,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_T"}}}
+{"type":"assistant/chunk","seq":81,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"WO"}}}
+{"type":"assistant/chunk","seq":82,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":83,"time":1783611772654,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":84,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":85,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":86,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"Second"}}}
+{"type":"assistant/chunk","seq":87,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
+{"type":"assistant/chunk","seq":88,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":89,"time":1783611772684,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
+{"type":"assistant/chunk","seq":90,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"return"}}}
+{"type":"assistant/chunk","seq":91,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":92,"time":1783611772713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":93,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":94,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"()"}}}
+{"type":"assistant/chunk","seq":95,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":96,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\"+"}}}
+{"type":"assistant/chunk","seq":97,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":98,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":99,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":100,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":101,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":102,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"();"}}}
+{"type":"assistant/chunk","seq":103,"time":1783611772772,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":104,"time":1783611772773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":105,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."}}}}
+{"type":"assistant/chunk","seq":106,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}}
+{"type":"assistant/chunk","seq":107,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}}}}
+{"type":"assistant/chunk","seq":108,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":109,"time":1783611772840,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."},{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"surfaceOp":"append"}
+{"type":"tool/call","seq":110,"time":1783611772840,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}
+{"type":"tool/code-dispatch","seq":111,"time":1783611772933,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"First echo"},"isError":false,"resultSummary":"CODE_ONE\n"}}
+{"type":"tool/code-dispatch","seq":112,"time":1783611772936,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Second echo"},"isError":false,"resultSummary":"CODE_TWO\n"}}
+{"type":"tool/result","seq":113,"time":1783611772937,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[110],"surfaceOp":"append"}
+{"type":"step/end","seq":114,"time":1783611772938,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":115,"time":1783611772938,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":116,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":117,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":118,"time":1783611773480,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":119,"time":1783611773511,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
+{"type":"assistant/chunk","seq":120,"time":1783611773512,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":121,"time":1783611773540,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
+{"type":"assistant/chunk","seq":122,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":123,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":124,"time":1783611773569,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}}
+{"type":"assistant/chunk","seq":125,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" for"}}}
+{"type":"assistant/chunk","seq":126,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":127,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":128,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":129,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":130,"time":1783611773626,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
+{"type":"assistant/chunk","seq":131,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":132,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":133,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":134,"time":1783611773654,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":135,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":136,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}}
+{"type":"assistant/chunk","seq":137,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":138,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}}
+{"type":"assistant/chunk","seq":139,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":140,"time":1783611773657,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}}
+{"type":"assistant/chunk","seq":141,"time":1783611773685,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
+{"type":"assistant/chunk","seq":142,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"}}}}
+{"type":"assistant/chunk","seq":143,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}}
+{"type":"assistant/chunk","seq":144,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}}}}
+{"type":"assistant/chunk","seq":145,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":146,"time":1783611773687,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}},"sourceEventSeqs":[116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"surfaceOp":"append"}
+{"type":"step/end","seq":147,"time":1783611773687,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":148,"time":1783611773687,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/code-mode/terminal.golden.txt b/examples/tui-agent/tests/snapshots/code-mode/terminal.golden.txt
new file mode 100644
index 0000000000..2850e0c7d0
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/code-mode/terminal.golden.txt
@@ -0,0 +1,79 @@
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=29 bufferRow=29
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: code-mode                                                                       │"
+  style 0-0 fg=bright-blue
+  style 2-27 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Using ONE run_code program: call the bash tool twice — exactly echo CODE_ONE then exactly echo    "
+  style 0-0 fg=bright-blue
+  style 65-77 fg=cyan
+  style 92-99 fg=cyan
+9| "▌ CODE_TWO — and return the two outputs joined with a plus sign. Then reply with that joined string "
+  style 0-0 fg=bright-blue
+  style 2-9 fg=cyan
+10| "▌ only and stop.                                                                                    "
+  style 0-0 fg=bright-blue
+11| "▌ "
+  style 0-0 fg=bright-blue
+12| <blank>
+13| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+14| " The user wants a single run_code program that calls bash twice, then returns the two outputs       "
+  style 1-99 fg=bright-black italic
+15| " joined with a plus sign. Let me write this.                                                        "
+  style 1-43 fg=bright-black italic
+16| <blank>
+17| "▌ "
+  style 0-0 fg=green
+18| "▌ ✓ const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"First echo\" });         "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-99 bold
+19| "▌ const o                                                                                           "
+  style 0-0 fg=green
+  style 2-8 bold
+20| "▌ CODE_ONE+CODE_TWO                                                                                 "
+  style 0-0 fg=green
+21| "▌ "
+  style 0-0 fg=green
+22| <blank>
+23| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+24| " The output is exactly what the user asked for: CODE_ONE+CODE_TWO                                   "
+  style 1-64 fg=bright-black italic
+25| <blank>
+26| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+27| " CODE_ONE+CODE_TWO                                                                                  "
+28| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+29| "                                                                                                    "
+  style 1-1 inverse
+30| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+31| "/workspace/project  ↑3.1k ↓158                 idle  reasoning:on  tools:compact"
+  style 0-49 dim
+  style 67-99 dim
+32-35| <blank>
diff --git a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.1.jsonl b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.1.jsonl
new file mode 100644
index 0000000000..25a6f76411
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.1.jsonl
@@ -0,0 +1,13 @@
+{"type":"session","version":0,"id":"22222222-2222-4222-8222-222222222222","createdAt":1783950001000,"cwd":"/tmp/advanced-acp","parentSession":"11111111-1111-4111-8111-111111111111"}
+{"type":"turn/start","seq":0,"time":1783957884563,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884563,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884564,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950001005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":5,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":6,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884564,"data":{"turn":1,"step":1,"content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"step/end","seq":10,"time":1783957884564,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":11,"time":1783957884564,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.2.jsonl b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.2.jsonl
new file mode 100644
index 0000000000..45d9043a4a
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.2.jsonl
@@ -0,0 +1,13 @@
+{"type":"session","version":0,"id":"33333333-3333-4333-8333-333333333333","createdAt":1783950002000,"cwd":"/tmp/advanced-acp","parentSession":"11111111-1111-4111-8111-111111111111"}
+{"type":"turn/start","seq":0,"time":1783957884700,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884700,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884700,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950002005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":5,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":6,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884701,"data":{"turn":1,"step":1,"content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"step/end","seq":10,"time":1783957884701,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":11,"time":1783957884701,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.jsonl b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.jsonl
new file mode 100644
index 0000000000..39f867984a
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/session.jsonl
@@ -0,0 +1,64 @@
+{"type":"session","version":0,"id":"11111111-1111-4111-8111-111111111111","createdAt":1783950000000,"cwd":"/tmp/advanced-acp"}
+{"type":"turn/start","seq":0,"time":1783957884479,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884479,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_ACP_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884486,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":1783950000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
+{"type":"assistant/chunk","seq":6,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783950000008,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783950000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884487,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"tool/call","seq":10,"time":1783957884487,"data":{"turn":1,"step":1,"callId":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}
+{"type":"tool/result","seq":11,"time":1783957884488,"data":{"turn":1,"step":1,"callId":"advanced-mount","content":[{"type":"text","text":"mounted dyn-1 (plugin \"snapshot-marker\", state: active)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
+{"type":"step/end","seq":12,"time":1783957884489,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":13,"time":1783957884489,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":14,"time":1783950000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":15,"time":1783950000016,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}
+{"type":"assistant/chunk","seq":16,"time":1783950000017,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}}
+{"type":"assistant/chunk","seq":17,"time":1783950000018,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":18,"time":1783950000019,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":19,"time":1783957884490,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[14,15,16,17,18],"surfaceOp":"append"}
+{"type":"tool/call","seq":20,"time":1783957884490,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}
+{"type":"tool/code-dispatch","seq":21,"time":1783957884560,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}
+{"type":"tool/result","seq":22,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[20],"surfaceOp":"append"}
+{"type":"step/end","seq":23,"time":1783957884561,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":24,"time":1783957884562,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":25,"time":1783950000026,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":26,"time":1783950000027,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-direct-child","name":"subagent","argumentsDelta":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}
+{"type":"assistant/chunk","seq":27,"time":1783950000028,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}
+{"type":"assistant/chunk","seq":28,"time":1783950000029,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":29,"time":1783950000030,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":30,"time":1783957884562,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[25,26,27,28,29],"surfaceOp":"append"}
+{"type":"tool/call","seq":31,"time":1783957884562,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}
+{"type":"tool/result","seq":32,"time":1783957884593,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false},"sourceEventSeqs":[31],"surfaceOp":"append"}
+{"type":"step/end","seq":33,"time":1783957884593,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":34,"time":1783957884594,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":35,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":36,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-workflow","name":"workflow","argumentsDelta":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-acp-snapshot\",\"description\":\"exercise one workflow child through ACP\"}}"}}}
+{"type":"assistant/chunk","seq":37,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-acp-snapshot\",\"description\":\"exercise one workflow child through ACP\"}}"}}}}
+{"type":"assistant/chunk","seq":38,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":39,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":40,"time":1783957884594,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-acp-snapshot\",\"description\":\"exercise one workflow child through ACP\"}}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[35,36,37,38,39],"surfaceOp":"append"}
+{"type":"tool/call","seq":41,"time":1783957884594,"data":{"turn":1,"step":4,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-acp-snapshot\",\"description\":\"exercise one workflow child through ACP\"}}"}}
+{"type":"tool/result","seq":42,"time":1783957884717,"data":{"turn":1,"step":4,"callId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-acp-snapshot\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[41],"surfaceOp":"append"}
+{"type":"step/end","seq":43,"time":1783957884718,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":44,"time":1783957884718,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":45,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":46,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-unmount","name":"cordis_unmount","argumentsDelta":"{\"id\":\"dyn-1\"}"}}}
+{"type":"assistant/chunk","seq":47,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}}}
+{"type":"assistant/chunk","seq":48,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":49,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":50,"time":1783957884719,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[45,46,47,48,49],"surfaceOp":"append"}
+{"type":"tool/call","seq":51,"time":1783957884719,"data":{"turn":1,"step":5,"callId":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}
+{"type":"tool/result","seq":52,"time":1783957884719,"data":{"turn":1,"step":5,"callId":"advanced-unmount","content":[{"type":"text","text":"unmounted dyn-1 (plugin \"snapshot-marker\")"}],"isError":false},"sourceEventSeqs":[51],"surfaceOp":"append"}
+{"type":"step/end","seq":53,"time":1783957884719,"data":{"turn":1,"step":5}}
+{"type":"step/start","seq":54,"time":1783957884720,"data":{"turn":1,"step":6}}
+{"type":"assistant/chunk","seq":55,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":56,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_ACP_OK"}}}
+{"type":"assistant/chunk","seq":57,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_ACP_OK"}}}}
+{"type":"assistant/chunk","seq":58,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":59,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":60,"time":1783957884720,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"ADVANCED_ACP_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[55,56,57,58,59],"surfaceOp":"append"}
+{"type":"step/end","seq":61,"time":1783957884721,"data":{"turn":1,"step":6}}
+{"type":"turn/end","seq":62,"time":1783957884721,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.golden.txt b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.golden.txt
new file mode 100644
index 0000000000..e4e6d0a040
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.golden.txt
@@ -0,0 +1,116 @@
+terminal 100x36 buffer=normal length=50 base=14 viewport=14
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=33 bufferRow=47
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: cordis-dynamic-toolchain                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-42 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use       "
+  style 0-0 fg=bright-blue
+9| "▌ run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a      "
+  style 0-0 fg=bright-blue
+10| "▌ direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then   "
+  style 0-0 fg=bright-blue
+11| "▌ reply with exactly ADVANCED_ACP_OK.                                                               "
+  style 0-0 fg=bright-blue
+12| "▌ "
+  style 0-0 fg=bright-blue
+13| <blank>
+14| "▌ "
+  style 0-0 fg=green
+15| "▌ ✓ Mount plugin into live cordis runtime                                                           "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-40 bold
+16| "▌ mounted dyn-1 (plugin \"snapshot-marker\", state: active)                                           "
+  style 0-0 fg=green
+17| "▌ "
+  style 0-0 fg=green
+18| <blank>
+19| "▌ "
+  style 0-0 fg=green
+20| "▌ ✓ return await tools.cordis_inspect({ what: 'dynamic' })                                          "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-57 bold
+21| "▌ ## dynamic                                                                                        "
+  style 0-0 fg=green
+22| "▌ - dyn-1: snapshot-marker [active]                                                                 "
+  style 0-0 fg=green
+23| "▌ "
+  style 0-0 fg=green
+24| <blank>
+25| "▌ "
+  style 0-0 fg=green
+26| "▌ ✓ subagent                                                                                        "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-11 bold
+27| "▌ DIRECT_CHILD_OK                                                                                   "
+  style 0-0 fg=green
+28| "▌ "
+  style 0-0 fg=green
+29| <blank>
+30| "▌ "
+  style 0-0 fg=green
+31| "▌ ✓ workflow: advanced-acp-snapshot                                                                 "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-34 bold
+32| "▌ workflow \"advanced-acp-snapshot\" completed (1 agent).                                             "
+  style 0-0 fg=green
+33| "▌ Return value:                                                                                     "
+  style 0-0 fg=green
+34| "▌ {                                                                                                 "
+  style 0-0 fg=green
+35| "▌   \"reply\": \"WORKFLOW_CHILD_OK\"                                                                    "
+  style 0-0 fg=green
+36| "▌ }                                                                                                 "
+  style 0-0 fg=green
+37| "▌ "
+  style 0-0 fg=green
+38| <blank>
+39| "▌ "
+  style 0-0 fg=green
+40| "▌ ✓ Unmount dyn-1                                                                                   "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-16 bold
+41| "▌ unmounted dyn-1 (plugin \"snapshot-marker\")                                                        "
+  style 0-0 fg=green
+42| "▌ "
+  style 0-0 fg=green
+43| <blank>
+44| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+45| " ADVANCED_ACP_OK                                                                                    "
+46| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+47| "                                                                                                    "
+  style 1-1 inverse
+48| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+49| "/workspace/project  ↑18 ↓18     idle  reasoning:on  tools:compact"
+  style 0-61 dim
+  style 67-99 dim
diff --git a/examples/tui-agent/tests/snapshots/dynamic-workflow/session.1.jsonl b/examples/tui-agent/tests/snapshots/dynamic-workflow/session.1.jsonl
new file mode 100644
index 0000000000..3d89428bbd
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/dynamic-workflow/session.1.jsonl
@@ -0,0 +1,36 @@
+{"type":"session","version":0,"id":"583a4db2-3350-436c-b4a5-5615fd159052","createdAt":1783600636316,"cwd":"/var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-vdJYjz","parentSession":"3fd7d599-56b1-493a-930d-f1fc5e1556e8"}
+{"type":"turn/start","seq":0,"time":1783600636316,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783600636316,"data":{"content":[{"type":"text","text":"Reply with exactly the word WF_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783600636316,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783600636317,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783600638073,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783600638073,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783600638173,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":11,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":12,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":13,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":14,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}}
+{"type":"assistant/chunk","seq":15,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}}
+{"type":"assistant/chunk","seq":16,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}}
+{"type":"assistant/chunk","seq":17,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}}
+{"type":"assistant/chunk","seq":18,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":19,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":20,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" nothing"}}}
+{"type":"assistant/chunk","seq":21,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" else"}}}
+{"type":"assistant/chunk","seq":22,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":23,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":24,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"WF"}}}
+{"type":"assistant/chunk","seq":25,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_CH"}}}
+{"type":"assistant/chunk","seq":26,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ILD"}}}
+{"type":"assistant/chunk","seq":27,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}}
+{"type":"assistant/chunk","seq":28,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"WF_CHILD_OK\" and nothing else."}}}}
+{"type":"assistant/chunk","seq":29,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WF_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":30,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3072,"reasoningTokens":18}}}}
+{"type":"assistant/chunk","seq":31,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":32,"time":1783600638281,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"WF_CHILD_OK\" and nothing else."},{"type":"text","text":"WF_CHILD_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3072,"reasoningTokens":18}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"}
+{"type":"step/end","seq":33,"time":1783600638281,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":34,"time":1783600638281,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/dynamic-workflow/session.jsonl b/examples/tui-agent/tests/snapshots/dynamic-workflow/session.jsonl
new file mode 100644
index 0000000000..3e0ae3da73
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/dynamic-workflow/session.jsonl
@@ -0,0 +1,209 @@
+{"type":"session","version":0,"id":"3fd7d599-56b1-493a-930d-f1fc5e1556e8","createdAt":1783600631835,"cwd":"/var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-vdJYjz"}
+{"type":"turn/start","seq":0,"time":1783600631838,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783600631838,"data":{"content":[{"type":"text","text":"Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783600631839,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783600631839,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783600634643,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783600634643,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}}
+{"type":"assistant/chunk","seq":11,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":12,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}}
+{"type":"assistant/chunk","seq":13,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":14,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":15,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" once"}}}
+{"type":"assistant/chunk","seq":16,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":17,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" specific"}}}
+{"type":"assistant/chunk","seq":18,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" parameters"}}}
+{"type":"assistant/chunk","seq":19,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":20,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}}
+{"type":"assistant/chunk","seq":21,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":22,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" carefully"}}}
+{"type":"assistant/chunk","seq":23,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" follow"}}}
+{"type":"assistant/chunk","seq":24,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":25,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" instructions"}}}
+{"type":"assistant/chunk","seq":26,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n\n"}}}
+{"type":"assistant/chunk","seq":27,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":28,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":29,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" args"}}}
+{"type":"assistant/chunk","seq":30,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" omitted"}}}
+{"type":"assistant/chunk","seq":31,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ("}}}
+{"type":"assistant/chunk","seq":32,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"so"}}}
+{"type":"assistant/chunk","seq":33,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":34,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" don"}}}
+{"type":"assistant/chunk","seq":35,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'t"}}}
+{"type":"assistant/chunk","seq":36,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" include"}}}
+{"type":"assistant/chunk","seq":37,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}}
+{"type":"assistant/chunk","seq":38,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":")\n"}}}
+{"type":"assistant/chunk","seq":39,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}}
+{"type":"assistant/chunk","seq":40,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":41,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" meta"}}}
+{"type":"assistant/chunk","seq":42,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}}
+{"type":"assistant/chunk","seq":43,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" {"}}}
+{"type":"assistant/chunk","seq":44,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":45,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"name"}}}
+{"type":"assistant/chunk","seq":46,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\":"}}}
+{"type":"assistant/chunk","seq":47,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":48,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"sn"}}}
+{"type":"assistant/chunk","seq":49,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"apshot"}}}
+{"type":"assistant/chunk","seq":50,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"-flow"}}}
+{"type":"assistant/chunk","seq":51,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\","}}}
+{"type":"assistant/chunk","seq":52,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":53,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"description"}}}
+{"type":"assistant/chunk","seq":54,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\":"}}}
+{"type":"assistant/chunk","seq":55,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":56,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"one"}}}
+{"type":"assistant/chunk","seq":57,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" child"}}}
+{"type":"assistant/chunk","seq":58,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" for"}}}
+{"type":"assistant/chunk","seq":59,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":60,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" snapshot"}}}
+{"type":"assistant/chunk","seq":61,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":62,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" }\n"}}}
+{"type":"assistant/chunk","seq":63,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}}
+{"type":"assistant/chunk","seq":64,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":65,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" script"}}}
+{"type":"assistant/chunk","seq":66,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}}
+{"type":"assistant/chunk","seq":67,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}}
+{"type":"assistant/chunk","seq":68,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" given"}}}
+{"type":"assistant/chunk","seq":69,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" verb"}}}
+{"type":"assistant/chunk","seq":70,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"atim"}}}
+{"type":"assistant/chunk","seq":71,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}}
+{"type":"assistant/chunk","seq":72,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"4"}}}
+{"type":"assistant/chunk","seq":73,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":74,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" After"}}}
+{"type":"assistant/chunk","seq":75,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}}
+{"type":"assistant/chunk","seq":76,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}}
+{"type":"assistant/chunk","seq":77,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
+{"type":"assistant/chunk","seq":78,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":79,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":80,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":81,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}}
+{"type":"assistant/chunk","seq":82,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}}
+{"type":"assistant/chunk","seq":83,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}}
+{"type":"assistant/chunk","seq":84,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}}
+{"type":"assistant/chunk","seq":85,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":86,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"\n\n"}}}
+{"type":"assistant/chunk","seq":87,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":88,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":89,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}}
+{"type":"assistant/chunk","seq":90,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":91,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":92,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":93,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":94,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":95,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":96,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":97,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"meta"}}}
+{"type":"assistant/chunk","seq":98,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":99,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":100,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"{\""}}}
+{"type":"assistant/chunk","seq":101,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"name"}}}
+{"type":"assistant/chunk","seq":102,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":103,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":104,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"sn"}}}
+{"type":"assistant/chunk","seq":105,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"apshot"}}}
+{"type":"assistant/chunk","seq":106,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"-flow"}}}
+{"type":"assistant/chunk","seq":107,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\","}}}
+{"type":"assistant/chunk","seq":108,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":109,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"description"}}}
+{"type":"assistant/chunk","seq":110,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":111,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":112,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"one"}}}
+{"type":"assistant/chunk","seq":113,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" child"}}}
+{"type":"assistant/chunk","seq":114,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" for"}}}
+{"type":"assistant/chunk","seq":115,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" the"}}}
+{"type":"assistant/chunk","seq":116,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" snapshot"}}}
+{"type":"assistant/chunk","seq":117,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":118,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":119,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":", "}}}
+{"type":"assistant/chunk","seq":120,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":121,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"script"}}}
+{"type":"assistant/chunk","seq":122,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":123,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":124,"time":1783600635764,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":125,"time":1783600635764,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\\n"}}}
+{"type":"assistant/chunk","seq":126,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"phase"}}}
+{"type":"assistant/chunk","seq":127,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"('"}}}
+{"type":"assistant/chunk","seq":128,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"Run"}}}
+{"type":"assistant/chunk","seq":129,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"')\\n"}}}
+{"type":"assistant/chunk","seq":130,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":131,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" reply"}}}
+{"type":"assistant/chunk","seq":132,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":133,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":134,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" agent"}}}
+{"type":"assistant/chunk","seq":135,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"('"}}}
+{"type":"assistant/chunk","seq":136,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"Reply"}}}
+{"type":"assistant/chunk","seq":137,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" with"}}}
+{"type":"assistant/chunk","seq":138,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" exactly"}}}
+{"type":"assistant/chunk","seq":139,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" the"}}}
+{"type":"assistant/chunk","seq":140,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" word"}}}
+{"type":"assistant/chunk","seq":141,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" WF"}}}
+{"type":"assistant/chunk","seq":142,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"_CH"}}}
+{"type":"assistant/chunk","seq":143,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"ILD"}}}
+{"type":"assistant/chunk","seq":144,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"_OK"}}}
+{"type":"assistant/chunk","seq":145,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" and"}}}
+{"type":"assistant/chunk","seq":146,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" nothing"}}}
+{"type":"assistant/chunk","seq":147,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" else"}}}
+{"type":"assistant/chunk","seq":148,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":".')\\n"}}}
+{"type":"assistant/chunk","seq":149,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"return"}}}
+{"type":"assistant/chunk","seq":150,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" {"}}}
+{"type":"assistant/chunk","seq":151,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" reply"}}}
+{"type":"assistant/chunk","seq":152,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" }\\n"}}}
+{"type":"assistant/chunk","seq":153,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":154,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":155,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully follow the instructions:\n\n1. args omitted (so I don't include it)\n2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }\n3. script = as given verbatim\n4. After it returns, reply with \"WORKFLOW_DONE\"\n\nLet me do exactly that."}}}}
+{"type":"assistant/chunk","seq":156,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}}}}
+{"type":"assistant/chunk","seq":157,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3174,"outputTokens":191,"cacheReadTokens":0,"reasoningTokens":88}}}}
+{"type":"assistant/chunk","seq":158,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":159,"time":1783600636247,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully follow the instructions:\n\n1. args omitted (so I don't include it)\n2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }\n3. script = as given verbatim\n4. After it returns, reply with \"WORKFLOW_DONE\"\n\nLet me do exactly that."},{"type":"tool-call","id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3174,"outputTokens":191,"cacheReadTokens":0,"reasoningTokens":88}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158],"surfaceOp":"append"}
+{"type":"tool/call","seq":160,"time":1783600636247,"data":{"turn":1,"step":1,"callId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}}
+{"type":"tool/result","seq":161,"time":1783600638304,"data":{"turn":1,"step":1,"callId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","content":[{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WF_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[160],"surfaceOp":"append"}
+{"type":"step/end","seq":162,"time":1783600638304,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":163,"time":1783600638305,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":164,"time":1783600640028,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":165,"time":1783600640028,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":166,"time":1783600640134,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}}
+{"type":"assistant/chunk","seq":167,"time":1783600640162,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}}
+{"type":"assistant/chunk","seq":168,"time":1783600640195,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}}
+{"type":"assistant/chunk","seq":169,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":170,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":171,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":172,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":173,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}}
+{"type":"assistant/chunk","seq":174,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}}
+{"type":"assistant/chunk","seq":175,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}}
+{"type":"assistant/chunk","seq":176,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}}
+{"type":"assistant/chunk","seq":177,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":178,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Now"}}}
+{"type":"assistant/chunk","seq":179,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":180,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}}
+{"type":"assistant/chunk","seq":181,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":182,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":183,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":184,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":185,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":186,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}}
+{"type":"assistant/chunk","seq":187,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}}
+{"type":"assistant/chunk","seq":188,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}}
+{"type":"assistant/chunk","seq":189,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}}
+{"type":"assistant/chunk","seq":190,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":191,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":192,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":193,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}}
+{"type":"assistant/chunk","seq":194,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":195,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":196,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WORK"}}}
+{"type":"assistant/chunk","seq":197,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"FL"}}}
+{"type":"assistant/chunk","seq":198,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OW"}}}
+{"type":"assistant/chunk","seq":199,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_D"}}}
+{"type":"assistant/chunk","seq":200,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":201,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly \"WORKFLOW_DONE\" and stop."}}}}
+{"type":"assistant/chunk","seq":202,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WORKFLOW_DONE"}}}}
+{"type":"assistant/chunk","seq":203,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":328,"outputTokens":36,"cacheReadTokens":3072,"reasoningTokens":30}}}}
+{"type":"assistant/chunk","seq":204,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":205,"time":1783600640865,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly \"WORKFLOW_DONE\" and stop."},{"type":"text","text":"WORKFLOW_DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":328,"outputTokens":36,"cacheReadTokens":3072,"reasoningTokens":30}},"sourceEventSeqs":[164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204],"surfaceOp":"append"}
+{"type":"step/end","seq":206,"time":1783600640865,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":207,"time":1783600640865,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/dynamic-workflow/terminal.golden.txt b/examples/tui-agent/tests/snapshots/dynamic-workflow/terminal.golden.txt
new file mode 100644
index 0000000000..459fddd90c
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/dynamic-workflow/terminal.golden.txt
@@ -0,0 +1,106 @@
+terminal 100x36 buffer=normal length=47 base=11 viewport=11
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=33 bufferRow=44
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: dynamic-workflow                                                                │"
+  style 0-0 fg=bright-blue
+  style 2-34 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\",     "
+  style 0-0 fg=bright-blue
+9| "▌ \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):     "
+  style 0-0 fg=bright-blue
+10| "▌ phase('Run')                                                                                      "
+  style 0-0 fg=bright-blue
+11| "▌ const reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')            "
+  style 0-0 fg=bright-blue
+12| "▌ return { reply }                                                                                  "
+  style 0-0 fg=bright-blue
+13| "▌ After the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any     "
+  style 0-0 fg=bright-blue
+14| "▌ other tool.                                                                                       "
+  style 0-0 fg=bright-blue
+15| "▌ "
+  style 0-0 fg=bright-blue
+16| <blank>
+17| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+18| " The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully "
+  style 1-99 fg=bright-black italic
+19| " follow the instructions:                                                                           "
+  style 1-24 fg=bright-black italic
+20| "                                                                                                    "
+21| " 1. args omitted (so I don't include it)                                                            "
+  style 1-3 fg=bright-blue
+  style 4-39 fg=bright-black italic
+22| " 2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }                 "
+  style 1-3 fg=bright-blue
+  style 4-82 fg=bright-black italic
+23| " 3. script = as given verbatim                                                                      "
+  style 1-3 fg=bright-blue
+  style 4-29 fg=bright-black italic
+24| " 4. After it returns, reply with \"WORKFLOW_DONE\"                                                    "
+  style 1-3 fg=bright-blue
+  style 4-47 fg=bright-black italic
+25| "                                                                                                    "
+26| " Let me do exactly that.                                                                            "
+  style 1-23 fg=bright-black italic
+27| <blank>
+28| "▌ "
+  style 0-0 fg=green
+29| "▌ ✓ workflow: snapshot-flow                                                                         "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-26 bold
+30| "▌ workflow \"snapshot-flow\" completed (1 agent).                                                     "
+  style 0-0 fg=green
+31| "▌ Return value:                                                                                     "
+  style 0-0 fg=green
+32| "▌ {                                                                                                 "
+  style 0-0 fg=green
+33| "▌   \"reply\": \"WF_CHILD_OK\"                                                                          "
+  style 0-0 fg=green
+34| "▌ }                                                                                                 "
+  style 0-0 fg=green
+35| "▌ "
+  style 0-0 fg=green
+36| <blank>
+37| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+38| " The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly  "
+  style 1-99 fg=bright-black italic
+39| " \"WORKFLOW_DONE\" and stop.                                                                          "
+  style 1-25 fg=bright-black italic
+40| <blank>
+41| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+42| " WORKFLOW_DONE                                                                                      "
+43| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+44| "                                                                                                    "
+  style 1-1 inverse
+45| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+46| "/workspace/project  ↑3.5k ↓227          idle  reasoning:on  tools:compact"
+  style 0-56 dim
+  style 67-99 dim
diff --git a/examples/tui-agent/tests/snapshots/multi-turn-conversation/session.jsonl b/examples/tui-agent/tests/snapshots/multi-turn-conversation/session.jsonl
new file mode 100644
index 0000000000..cd32072eaa
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/multi-turn-conversation/session.jsonl
@@ -0,0 +1,65 @@
+{"type":"session","version":0,"id":"228b7b82-84ed-49b7-a567-981c03b28c77","createdAt":1783352113760,"cwd":"/tmp/acp-snap-cwd-aN2GRR"}
+{"type":"turn/start","seq":0,"time":1783352113765,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783352113765,"data":{"content":[{"type":"text","text":"Reply with exactly the word: ONE. No tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783352113767,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783352113768,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783352114428,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783352114428,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783352114542,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783352114570,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783352114571,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783352114571,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783352114571,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":11,"time":1783352114572,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":12,"time":1783352114600,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":13,"time":1783352114601,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":14,"time":1783352114602,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}}
+{"type":"assistant/chunk","seq":15,"time":1783352114602,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":16,"time":1783352114602,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":17,"time":1783352114603,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":18,"time":1783352114627,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":19,"time":1783352114628,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}}
+{"type":"assistant/chunk","seq":20,"time":1783352114657,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" no"}}}
+{"type":"assistant/chunk","seq":21,"time":1783352114658,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
+{"type":"assistant/chunk","seq":22,"time":1783352114658,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":23,"time":1783352114658,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":24,"time":1783352114658,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":25,"time":1783352114687,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"ONE\" and use no tools."}}}}
+{"type":"assistant/chunk","seq":26,"time":1783352114687,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"ONE"}}}}
+{"type":"assistant/chunk","seq":27,"time":1783352114687,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2864,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":18}}}}
+{"type":"assistant/chunk","seq":28,"time":1783352114687,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":29,"time":1783352114690,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"ONE\" and use no tools."},{"type":"text","text":"ONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":2864,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":18}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28],"surfaceOp":"append"}
+{"type":"step/end","seq":30,"time":1783352114690,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":31,"time":1783352114690,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"turn/start","seq":32,"time":1783352114699,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":33,"time":1783352114699,"data":{"content":[{"type":"text","text":"Reply with exactly the word: TWO. No tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":34,"time":1783352114700,"data":{"turn":2,"step":1}}
+{"type":"assistant/chunk","seq":35,"time":1783352115341,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":36,"time":1783352115341,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":37,"time":1783352115465,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":38,"time":1783352115492,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":39,"time":1783352115493,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":40,"time":1783352115493,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":41,"time":1783352115493,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":42,"time":1783352115521,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":43,"time":1783352115521,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":44,"time":1783352115521,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":45,"time":1783352115552,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}}
+{"type":"assistant/chunk","seq":46,"time":1783352115552,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":47,"time":1783352115552,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"T"}}}
+{"type":"assistant/chunk","seq":48,"time":1783352115552,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":49,"time":1783352115552,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":50,"time":1783352115580,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":51,"time":1783352115580,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" no"}}}
+{"type":"assistant/chunk","seq":52,"time":1783352115580,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
+{"type":"assistant/chunk","seq":53,"time":1783352115580,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":54,"time":1783352115609,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":55,"time":1783352115609,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":1,"text":"T"}}}
+{"type":"assistant/chunk","seq":56,"time":1783352115609,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
+{"type":"assistant/chunk","seq":57,"time":1783352115610,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"TWO\" and no tools."}}}}
+{"type":"assistant/chunk","seq":58,"time":1783352115610,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"TWO"}}}}
+{"type":"assistant/chunk","seq":59,"time":1783352115610,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":64,"outputTokens":21,"cacheReadTokens":2816,"reasoningTokens":18}}}}
+{"type":"assistant/chunk","seq":60,"time":1783352115610,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":61,"time":1783352115611,"data":{"turn":2,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"TWO\" and no tools."},{"type":"text","text":"TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":64,"outputTokens":21,"cacheReadTokens":2816,"reasoningTokens":18}},"sourceEventSeqs":[35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60],"surfaceOp":"append"}
+{"type":"step/end","seq":62,"time":1783352115611,"data":{"turn":2,"step":1}}
+{"type":"turn/end","seq":63,"time":1783352115611,"data":{"turn":2,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.golden.txt b/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.golden.txt
new file mode 100644
index 0000000000..d56db72ccb
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.golden.txt
@@ -0,0 +1,70 @@
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=28 bufferRow=28
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: multi-turn-conversation                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-41 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Reply with exactly the word: ONE. No tools.                                                       "
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+12| " The user wants me to reply with exactly the word \"ONE\" and use no tools.                           "
+  style 1-72 fg=bright-black italic
+13| <blank>
+14| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+15| " ONE                                                                                                "
+16| <blank>
+17| "▌ "
+  style 0-0 fg=bright-blue
+18| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+19| "▌ Reply with exactly the word: TWO. No tools.                                                       "
+  style 0-0 fg=bright-blue
+20| "▌ "
+  style 0-0 fg=bright-blue
+21| <blank>
+22| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+23| " The user wants me to reply with exactly the word \"TWO\" and no tools.                               "
+  style 1-68 fg=bright-black italic
+24| <blank>
+25| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+26| " TWO                                                                                                "
+27| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+28| "                                                                                                    "
+  style 1-1 inverse
+29| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+30| "/workspace/project  ↑2.9k ↓41    idle  reasoning:on  tools:compact"
+  style 0-62 dim
+  style 67-99 dim
+31-35| <blank>
diff --git a/examples/tui-agent/tests/snapshots/parallel-file-reads/session.jsonl b/examples/tui-agent/tests/snapshots/parallel-file-reads/session.jsonl
new file mode 100644
index 0000000000..81503dc4cf
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/parallel-file-reads/session.jsonl
@@ -0,0 +1,28 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Use the read tool twice in the same assistant message: read a.txt and b.txt. Then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_read_a","name":"read","argumentsDelta":"{\"file_path\":\"a.txt\"}"}}}
+{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"}}}}
+{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_read_b","name":"read","argumentsDelta":"{\"file_path\":\"b.txt\"}"}}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":12,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"},{"type":"tool-call","id":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8,9,10,11],"surfaceOp":"append"}
+{"type":"tool/call","seq":13,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"}}
+{"type":"tool/call","seq":14,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}}
+{"type":"tool/result","seq":15,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_a","content":[{"type":"text","text":"<path>{{cwd}}/a.txt</path>\n<type>file</type>\n<content>\n1: alpha\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[13],"surfaceOp":"append"}
+{"type":"tool/result","seq":16,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_b","content":[{"type":"text","text":"<path>{{cwd}}/b.txt</path>\n<type>file</type>\n<content>\n1: beta\n\n(End of file - total 1 lines)\n</content>"}],"isError":false},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","seq":17,"time":0,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":18,"time":0,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":20,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
+{"type":"assistant/chunk","seq":21,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":1}}}}
+{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":24,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":1}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
+{"type":"step/end","seq":25,"time":0,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":26,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/parallel-file-reads/terminal.golden.txt b/examples/tui-agent/tests/snapshots/parallel-file-reads/terminal.golden.txt
new file mode 100644
index 0000000000..f4c3d83b3d
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/parallel-file-reads/terminal.golden.txt
@@ -0,0 +1,91 @@
+terminal 100x36 buffer=normal length=39 base=3 viewport=3
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=33 bufferRow=36
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: parallel-file-reads                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-37 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Use the read tool twice in the same assistant message: read a.txt and b.txt. Then reply DONE.     "
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| "▌ "
+  style 0-0 fg=green
+12| "▌ ✓ Read a.txt                                                                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-13 bold
+13| "▌ <path>/workspace/project/a.txt</path>                               "
+  style 0-0 fg=green
+14| "▌ <type>file</type>                                                                                 "
+  style 0-0 fg=green
+15| "▌ <content>                                                                                         "
+  style 0-0 fg=green
+16| "▌ 1: alpha                                                                                          "
+  style 0-0 fg=green
+17| "▌                                                                                                   "
+  style 0-0 fg=green
+18| "▌ (End of file - total 1 lines)                                                                     "
+  style 0-0 fg=green
+19| "▌ </content>                                                                                        "
+  style 0-0 fg=green
+20| "▌ "
+  style 0-0 fg=green
+21| <blank>
+22| "▌ "
+  style 0-0 fg=green
+23| "▌ ✓ Read b.txt                                                                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-13 bold
+24| "▌ <path>/workspace/project/b.txt</path>                               "
+  style 0-0 fg=green
+25| "▌ <type>file</type>                                                                                 "
+  style 0-0 fg=green
+26| "▌ <content>                                                                                         "
+  style 0-0 fg=green
+27| "▌ 1: beta                                                                                           "
+  style 0-0 fg=green
+28| "▌                                                                                                   "
+  style 0-0 fg=green
+29| "▌ (End of file - total 1 lines)                                                                     "
+  style 0-0 fg=green
+30| "▌ </content>                                                                                        "
+  style 0-0 fg=green
+31| "▌ "
+  style 0-0 fg=green
+32| <blank>
+33| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+34| " DONE                                                                                               "
+35| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+36| "                                                                                                    "
+  style 1-1 inverse
+37| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+38| "/workspace/project  ↑20 ↓6           idle  reasoning:on  tools:compact"
+  style 0-55 dim
+  style 67-99 dim
diff --git a/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/a.txt b/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/a.txt
new file mode 100644
index 0000000000..4a58007052
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/a.txt
@@ -0,0 +1 @@
+alpha
diff --git a/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/b.txt b/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/b.txt
new file mode 100644
index 0000000000..65b2df87f7
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/parallel-file-reads/workspace/b.txt
@@ -0,0 +1 @@
+beta
diff --git a/examples/tui-agent/tests/snapshots/todo-plan/session.jsonl b/examples/tui-agent/tests/snapshots/todo-plan/session.jsonl
new file mode 100644
index 0000000000..909afc44cd
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/todo-plan/session.jsonl
@@ -0,0 +1,134 @@
+{"type":"session","version":0,"id":"b0f1f758-dcf0-474e-851d-e62c11ec0a09","createdAt":1783352057652,"cwd":"/tmp/acp-snap-cwd-AYilT7"}
+{"type":"turn/start","seq":0,"time":1783352057655,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783352057655,"data":{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783352057657,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783352057657,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783352058320,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783352058320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783352058426,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783352058466,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783352058467,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783352058467,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783352058467,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}}
+{"type":"assistant/chunk","seq":11,"time":1783352058467,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":12,"time":1783352058484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" todo"}}}
+{"type":"assistant/chunk","seq":13,"time":1783352058484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_write"}}}
+{"type":"assistant/chunk","seq":14,"time":1783352058484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":15,"time":1783352058484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":16,"time":1783352058485,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" record"}}}
+{"type":"assistant/chunk","seq":17,"time":1783352058511,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":18,"time":1783352058512,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plan"}}}
+{"type":"assistant/chunk","seq":19,"time":1783352058513,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":20,"time":1783352058513,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":21,"time":1783352058513,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" three"}}}
+{"type":"assistant/chunk","seq":22,"time":1783352058514,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" todos"}}}
+{"type":"assistant/chunk","seq":23,"time":1783352058540,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" in"}}}
+{"type":"assistant/chunk","seq":24,"time":1783352058540,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":25,"time":1783352058571,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" specified"}}}
+{"type":"assistant/chunk","seq":26,"time":1783352058572,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" status"}}}
+{"type":"assistant/chunk","seq":27,"time":1783352058597,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"es"}}}
+{"type":"assistant/chunk","seq":28,"time":1783352058597,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
+{"type":"assistant/chunk","seq":29,"time":1783352058597,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
+{"type":"assistant/chunk","seq":30,"time":1783352058597,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":31,"time":1783352058626,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":32,"time":1783352058626,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":33,"time":1783352058626,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":34,"time":1783352058626,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":35,"time":1783352058626,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":36,"time":1783352058717,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":37,"time":1783352058717,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":38,"time":1783352058746,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":39,"time":1783352058747,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":40,"time":1783352058747,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"t"}}}
+{"type":"assistant/chunk","seq":41,"time":1783352058747,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"odos"}}}
+{"type":"assistant/chunk","seq":42,"time":1783352058775,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":43,"time":1783352058775,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":44,"time":1783352058776,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"["}}}
+{"type":"assistant/chunk","seq":45,"time":1783352058805,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"{\""}}}
+{"type":"assistant/chunk","seq":46,"time":1783352058806,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"content"}}}
+{"type":"assistant/chunk","seq":47,"time":1783352058806,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":48,"time":1783352058806,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":49,"time":1783352058806,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"read"}}}
+{"type":"assistant/chunk","seq":50,"time":1783352058806,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" the"}}}
+{"type":"assistant/chunk","seq":51,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" code"}}}
+{"type":"assistant/chunk","seq":52,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\","}}}
+{"type":"assistant/chunk","seq":53,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":54,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"status"}}}
+{"type":"assistant/chunk","seq":55,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":56,"time":1783352058832,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":57,"time":1783352058862,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"in"}}}
+{"type":"assistant/chunk","seq":58,"time":1783352058863,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"_pro"}}}
+{"type":"assistant/chunk","seq":59,"time":1783352058863,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"gress"}}}
+{"type":"assistant/chunk","seq":60,"time":1783352058863,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\"},"}}}
+{"type":"assistant/chunk","seq":61,"time":1783352058863,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" {\""}}}
+{"type":"assistant/chunk","seq":62,"time":1783352058863,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"content"}}}
+{"type":"assistant/chunk","seq":63,"time":1783352058889,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":64,"time":1783352058890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":65,"time":1783352058890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"write"}}}
+{"type":"assistant/chunk","seq":66,"time":1783352058890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" the"}}}
+{"type":"assistant/chunk","seq":67,"time":1783352058890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" fix"}}}
+{"type":"assistant/chunk","seq":68,"time":1783352058890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\","}}}
+{"type":"assistant/chunk","seq":69,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":70,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"status"}}}
+{"type":"assistant/chunk","seq":71,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":72,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":73,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"pending"}}}
+{"type":"assistant/chunk","seq":74,"time":1783352058918,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\"},"}}}
+{"type":"assistant/chunk","seq":75,"time":1783352058947,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" {\""}}}
+{"type":"assistant/chunk","seq":76,"time":1783352058947,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"content"}}}
+{"type":"assistant/chunk","seq":77,"time":1783352058947,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":78,"time":1783352058947,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":79,"time":1783352058947,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"run"}}}
+{"type":"assistant/chunk","seq":80,"time":1783352058948,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" the"}}}
+{"type":"assistant/chunk","seq":81,"time":1783352058976,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" tests"}}}
+{"type":"assistant/chunk","seq":82,"time":1783352058976,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\","}}}
+{"type":"assistant/chunk","seq":83,"time":1783352058976,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":84,"time":1783352058976,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"status"}}}
+{"type":"assistant/chunk","seq":85,"time":1783352058977,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\":"}}}
+{"type":"assistant/chunk","seq":86,"time":1783352058977,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":" \""}}}
+{"type":"assistant/chunk","seq":87,"time":1783352059004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"pending"}}}
+{"type":"assistant/chunk","seq":88,"time":1783352059005,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":89,"time":1783352059005,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"}]"}}}
+{"type":"assistant/chunk","seq":90,"time":1783352059033,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":91,"time":1783352059095,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the todo_write tool to record a plan with exactly three todos in the specified statuses, then reply with \"DONE\"."}}}}
+{"type":"assistant/chunk","seq":92,"time":1783352059096,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}}}}
+{"type":"assistant/chunk","seq":93,"time":1783352059096,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2913,"outputTokens":121,"cacheReadTokens":0,"reasoningTokens":31}}}}
+{"type":"assistant/chunk","seq":94,"time":1783352059096,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":95,"time":1783352059099,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the todo_write tool to record a plan with exactly three todos in the specified statuses, then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":2913,"outputTokens":121,"cacheReadTokens":0,"reasoningTokens":31}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94],"surfaceOp":"append"}
+{"type":"tool/call","seq":96,"time":1783352059099,"data":{"turn":1,"step":1,"callId":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}}
+{"type":"todo/write","seq":97,"time":1783352059100,"data":{"todos":[{"content":"read the code","status":"in_progress"},{"content":"write the fix","status":"pending"},{"content":"run the tests","status":"pending"}]}}
+{"type":"tool/result","seq":98,"time":1783352059101,"data":{"turn":1,"step":1,"callId":"call_00_fjAnBThbDjxepBtp3hDt3264","content":[{"type":"text","text":"Updated todo list: 2 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[96],"surfaceOp":"append"}
+{"type":"step/end","seq":99,"time":1783352059101,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":100,"time":1783352059102,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":101,"time":1783352059732,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":102,"time":1783352059733,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":103,"time":1783352059835,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" todos"}}}
+{"type":"assistant/chunk","seq":104,"time":1783352059863,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" have"}}}
+{"type":"assistant/chunk","seq":105,"time":1783352059863,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" been"}}}
+{"type":"assistant/chunk","seq":106,"time":1783352059864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" written"}}}
+{"type":"assistant/chunk","seq":107,"time":1783352059864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}}
+{"type":"assistant/chunk","seq":108,"time":1783352059892,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":109,"time":1783352059892,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Now"}}}
+{"type":"assistant/chunk","seq":110,"time":1783352059893,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":111,"time":1783352059893,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}}
+{"type":"assistant/chunk","seq":112,"time":1783352059920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}}
+{"type":"assistant/chunk","seq":113,"time":1783352059920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":114,"time":1783352059921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":115,"time":1783352059921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":116,"time":1783352059921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":117,"time":1783352059950,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}}
+{"type":"assistant/chunk","seq":118,"time":1783352059950,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}}
+{"type":"assistant/chunk","seq":119,"time":1783352059950,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":120,"time":1783352059950,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":121,"time":1783352059951,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":122,"time":1783352059951,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":123,"time":1783352059979,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":124,"time":1783352059979,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
+{"type":"assistant/chunk","seq":125,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":126,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The todos have been written successfully. Now I just need to reply with the single word \"DONE\"."}}}}
+{"type":"assistant/chunk","seq":127,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":128,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":237,"outputTokens":24,"cacheReadTokens":2816,"reasoningTokens":21}}}}
+{"type":"assistant/chunk","seq":129,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":130,"time":1783352059981,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The todos have been written successfully. Now I just need to reply with the single word \"DONE\"."},{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":237,"outputTokens":24,"cacheReadTokens":2816,"reasoningTokens":21}},"sourceEventSeqs":[101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129],"surfaceOp":"append"}
+{"type":"step/end","seq":131,"time":1783352059981,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":132,"time":1783352059981,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/todo-plan/terminal.golden.txt b/examples/tui-agent/tests/snapshots/todo-plan/terminal.golden.txt
new file mode 100644
index 0000000000..527e6e4016
--- /dev/null
+++ b/examples/tui-agent/tests/snapshots/todo-plan/terminal.golden.txt
@@ -0,0 +1,81 @@
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH TUI snapshot"
+cursor hidden column=1 viewportRow=33 bufferRow=33
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Recorded replay: todo-plan                                                                       │"
+  style 0-0 fg=bright-blue
+  style 2-27 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), "
+  style 0-0 fg=bright-blue
+9| "▌ \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then "
+  style 0-0 fg=bright-blue
+10| "▌ reply with the single word DONE and stop.                                                         "
+  style 0-0 fg=bright-blue
+11| "▌ "
+  style 0-0 fg=bright-blue
+12| <blank>
+13| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+14| " The user wants me to use the todo_write tool to record a plan with exactly three todos in the      "
+  style 1-99 fg=bright-black italic
+15| " specified statuses, then reply with \"DONE\".                                                        "
+  style 1-43 fg=bright-black italic
+16| <blank>
+17| "▌ "
+  style 0-0 fg=green
+18| "▌ ✓ Update todo list                                                                                "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-19 bold
+19| "▌ Updated todo list: 2 pending, 1 in progress, 0 completed.                                         "
+  style 0-0 fg=green
+20| "▌ "
+  style 0-0 fg=green
+21| <blank>
+22| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+23| " The todos have been written successfully. Now I just need to reply with the single word \"DONE\".    "
+  style 1-95 fg=bright-black italic
+24| <blank>
+25| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+26| " DONE                                                                                               "
+27| <blank>
+28| "Plan"
+  style 0-3 fg=bright-blue bold
+29| "  ● read the code"
+  style 2-2 fg=yellow
+30| "  ○ write the fix"
+  style 2-2 dim
+31| "  ○ run the tests"
+  style 2-2 dim
+32| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+33| "                                                                                                    "
+  style 1-1 inverse
+34| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+35| "/workspace/project  ↑3.1k ↓145                 idle  reasoning:on  tools:compact"
+  style 0-49 dim
+  style 67-99 dim
diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts
new file mode 100644
index 0000000000..7cc8aebe32
--- /dev/null
+++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts
@@ -0,0 +1,172 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
+
+const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+const PTY_DRIVER = String.raw`
+import errno, json, os, pty, select, signal, sys, time
+node, launch_args_json, launch_env_json, cwd, resume_session_id, scenario = sys.argv[1:]
+env = os.environ.copy()
+env.update(json.loads(launch_env_json))
+env.update({
+    "COLUMNS": "100",
+    "LINES": "30",
+})
+if resume_session_id:
+    env["RESUME_SESSION_ID"] = resume_session_id
+pid, fd = pty.fork()
+if pid == 0:
+    os.chdir(cwd)
+    os.execvpe(node, [node, *json.loads(launch_args_json)], env)
+
+output = bytearray()
+answered_question = False
+sent_prompt = False
+sent_exit = False
+deadline = time.monotonic() + 25
+status = None
+while time.monotonic() < deadline:
+    ready, _, _ = select.select([fd], [], [], 0.05)
+    if ready:
+        try:
+            chunk = os.read(fd, 65536)
+        except OSError as error:
+            if error.errno != errno.EIO:
+                raise
+            chunk = b""
+        if chunk:
+            output.extend(chunk)
+    if scenario == "conversation" and not sent_prompt and b"scripted TUI ready." in output:
+        os.write(fd, b"exercise the TUI\r")
+        sent_prompt = True
+    if scenario == "conversation" and sent_prompt and not answered_question and b"How should the scripted run proceed?" in output:
+        os.write(fd, b"\r")
+        answered_question = True
+    if scenario == "conversation" and answered_question and not sent_exit and b"Decision received. Scripted TUI run complete." in output:
+        os.write(fd, b"/exit\r")
+        sent_exit = True
+    if scenario == "boot" and not sent_exit and b"TUI agent ready." in output:
+        os.write(fd, b"/exit\r")
+        sent_exit = True
+    waited, candidate = os.waitpid(pid, os.WNOHANG)
+    if waited == pid:
+        status = candidate
+        break
+
+if status is None:
+    os.kill(pid, signal.SIGKILL)
+    _, status = os.waitpid(pid, 0)
+sys.stdout.buffer.write(output)
+if scenario == "resume-failure":
+    if b'ui-tui: session "missing-session" failed to start:' not in output:
+        sys.stderr.write("TUI did not render the startup failure before timeout\n")
+        sys.exit(126)
+    if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 1:
+        sys.stderr.write("TUI startup failure did not exit with status 1\n")
+        sys.exit(127)
+elif scenario == "conversation":
+    if not sent_prompt:
+        sys.stderr.write("TUI did not render the scripted welcome marker before timeout\n")
+        sys.exit(128)
+    if not answered_question:
+        sys.stderr.write("TUI did not render the user-question dialog before timeout\n")
+        sys.exit(129)
+    if not sent_exit:
+        sys.stderr.write("TUI did not finish the scripted tool round-trip before timeout\n")
+        sys.exit(130)
+    if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 0:
+        sys.stderr.write("TUI scripted conversation did not exit cleanly\n")
+        sys.exit(131)
+else:
+    if not sent_exit:
+        sys.stderr.write("TUI did not render its welcome marker before timeout\n")
+        sys.exit(124)
+    if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 0:
+        sys.stderr.write("TUI child did not exit cleanly\n")
+        sys.exit(125)
+`
+
+interface TuiLoaderSmokeOptions {
+  config?: string
+  resumeSessionId?: string
+  scenario?: 'boot' | 'conversation' | 'resume-failure'
+}
+
+async function runTuiLoaderSmoke(options: TuiLoaderSmokeOptions = {}): Promise<string> {
+  const cwd = await mkdtemp(join(tmpdir(), 'tui-agent-smoke-'))
+  try {
+    const launch = resolveExampleLaunch({
+      srcBin: binScript,
+      configArgs: [options.config ?? configPath],
+      tsconfigPath,
+      exposeInternals: true,
+      env: {
+        DEEPSEEK_API_KEY: 'keyless-tui-no-call',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      },
+    })
+    return await new Promise((resolve, reject) => {
+      const child = spawn('python3', [
+        '-c',
+        PTY_DRIVER,
+        launch.command,
+        JSON.stringify(launch.args),
+        JSON.stringify(launch.env),
+        cwd,
+        options.resumeSessionId ?? '',
+        options.scenario ?? 'boot',
+      ], { stdio: ['ignore', 'pipe', 'pipe'] })
+      let stdout = ''
+      let stderr = ''
+      child.stdout.setEncoding('utf8')
+      child.stdout.on('data', (chunk: string) => { stdout += chunk })
+      child.stderr.setEncoding('utf8')
+      child.stderr.on('data', (chunk: string) => { stderr += chunk })
+      child.once('error', reject)
+      child.once('exit', (code) => {
+        if (code === 0) resolve(stdout)
+        else reject(new Error(`TUI PTY smoke exited ${String(code)}. stdout:\n${stdout}\nstderr:\n${stderr}`))
+      })
+    })
+  } finally {
+    await rm(cwd, { recursive: true, force: true })
+  }
+}
+
+describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
+  it('boots pi-tui, renders the configured banner, accepts /exit, and restores the terminal', async () => {
+    const output = await runTuiLoaderSmoke()
+    expect(output).toContain('DEEPSEEK')
+    expect(output).toContain('TUI agent ready.')
+    expect(output).toContain('\u001B[?2004l')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('streams a response, answers a user-question dialog, completes the tool round-trip, and exits cleanly', async () => {
+    const output = await runTuiLoaderSmoke({ config: scriptedConfigPath, scenario: 'conversation' })
+    expect(output).toContain('I need one decision before I continue.')
+    expect(output).toContain(String.raw`\x1b]2;MODEL_CONTROLLED\x07`)
+    expect(output).toContain(String.raw`\x1b[999CMODEL_CURSOR`)
+    expect(output).toContain(String.raw`\x9b31mMODEL_C1`)
+    expect(output).not.toContain('\u001B]2;MODEL_CONTROLLED\u0007')
+    expect(output).not.toContain('\u001B[999CMODEL_CURSOR')
+    expect(output).not.toContain('\u009B31mMODEL_C1')
+    expect(output).toContain('How should the scripted run proceed?')
+    expect(output).toContain('Safe')
+    expect(output).toContain('Decision received. Scripted TUI run complete.')
+    expect(output).toContain('\u001B[?2004l')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('prints a config-resume failure and exits instead of leaving a blank terminal', async () => {
+    const output = await runTuiLoaderSmoke({ resumeSessionId: 'missing-session', scenario: 'resume-failure' })
+    expect(output).toContain('ui-tui: session "missing-session" failed to start:')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts
new file mode 100644
index 0000000000..c0537021e8
--- /dev/null
+++ b/examples/tui-agent/tests/tui.snapshot.ts
@@ -0,0 +1,330 @@
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scrubRequestHeaders } from '@deepseek-ai/dsh-acp-snapshot'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent'
+import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
+import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
+import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import { createTuiChat } from '@deepseek-ai/dsh-tui'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread'
+import { HeadlessTerminal } from '../../../packages/ui/tui/tests/headless-terminal.ts'
+
+const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
+// Keep pre-normalization layout widths identical across macOS and Linux.
+const SNAPSHOT_TMP_ROOT = process.platform === 'win32' ? tmpdir() : '/tmp'
+const PROVIDERS = [{ id: 'deepseek', models: [{ id: 'deepseek-v4-flash' }] }]
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
+
+type SnapshotMode = 'replay' | 'record' | 'refresh'
+type Composition = 'native' | 'code' | 'advanced'
+
+interface Scenario {
+  name: string
+  composition: Composition
+  expectedTools: string[]
+  expectedEventCounts?: Record<string, number>
+  childSessions?: number
+  recorded: boolean
+  seedWorkspace?: boolean
+}
+
+const SCENARIOS: Scenario[] = [
+  {
+    name: 'multi-turn-conversation',
+    composition: 'native',
+    expectedTools: [],
+    recorded: true,
+  },
+  {
+    name: 'todo-plan',
+    composition: 'native',
+    expectedTools: ['todo_write'],
+    expectedEventCounts: { 'todo/write': 1 },
+    recorded: true,
+  },
+  {
+    name: 'bash-terminal-card',
+    composition: 'native',
+    expectedTools: ['bash'],
+    recorded: true,
+  },
+  {
+    name: 'parallel-file-reads',
+    composition: 'native',
+    expectedTools: ['read', 'read'],
+    recorded: true,
+    seedWorkspace: true,
+  },
+  {
+    name: 'code-mode',
+    composition: 'code',
+    expectedTools: ['run_code'],
+    expectedEventCounts: { 'tool/code-dispatch': 2 },
+    recorded: true,
+  },
+  {
+    name: 'dynamic-workflow',
+    composition: 'native',
+    expectedTools: ['workflow'],
+    childSessions: 1,
+    recorded: true,
+  },
+  {
+    name: 'cordis-dynamic-toolchain',
+    composition: 'advanced',
+    expectedTools: ['cordis_mount', 'run_code', 'subagent', 'workflow', 'cordis_unmount'],
+    expectedEventCounts: { 'tool/code-dispatch': 1 },
+    childSessions: 2,
+    recorded: false,
+  },
+]
+
+function snapshotModeFromEnv(value: string | undefined): SnapshotMode {
+  if (value === undefined || value === '' || value === 'replay') return 'replay'
+  if (value === 'record' || value === 'refresh') return value
+  throw new Error(`DSH_SNAPSHOT must be replay, record, or refresh; got ${JSON.stringify(value)}`)
+}
+
+const MODE = snapshotModeFromEnv(process.env.DSH_SNAPSHOT)
+const observedScenarios = new Set<string>()
+
+function scenarioDir(scenario: Scenario): string {
+  return join(SNAPSHOTS_DIR, scenario.name)
+}
+
+function childFixturePaths(scenario: Scenario): string[] {
+  return Array.from(
+    { length: scenario.childSessions ?? 0 },
+    (_, index) => join(scenarioDir(scenario), `session.${index + 1}.jsonl`),
+  )
+}
+
+function userPrompts(rawLog: string): string[] {
+  return parseSessionLog(rawLog).flatMap((event) => {
+    if (event.type !== 'user/message' || event.data.source.kind !== 'user') return []
+    const text = event.data.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    return text.length > 0 ? [text] : []
+  })
+}
+
+function rawSessionLog(session: Session): string {
+  return [
+    JSON.stringify({ type: 'session', ...session.header }),
+    ...session.events.map(event => JSON.stringify(event)),
+    '',
+  ].join('\n')
+}
+
+function normalizeTerminalSnapshot(snapshot: string, cwd: string): string {
+  return snapshot
+    .split(`/private${cwd}`).join('/workspace/project')
+    .split(cwd).join('/workspace/project')
+    .replace(UUID_RE, '{{uuid}}')
+}
+
+async function settleTerminal(terminal: HeadlessTerminal): Promise<void> {
+  let stable = 0
+  for (let attempt = 0; attempt < 20 && stable < 3; attempt++) {
+    const before = terminal.frames
+    await new Promise(resolve => setTimeout(resolve, 10))
+    await terminal.flush()
+    stable = terminal.frames === before ? stable + 1 : 0
+  }
+  if (stable < 3) throw new Error('TUI frames did not quiesce within 200ms')
+}
+
+async function mountScenarioContext(
+  scenario: Scenario,
+  cwd: string,
+  fixtureFile: string,
+  childFiles: string[],
+): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(AgentCore, {
+    agents: [],
+    dshHome: join(cwd, '.dsh'),
+    workspaceContext: false,
+    tools: { mode: scenario.composition === 'code' ? 'code' : scenario.composition === 'advanced' ? 'both' : 'native' },
+    skills: { local: { agentsHome: join(cwd, '.agents') } },
+  })
+  await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
+  await ctx.plugin(LocalFileSystem, { cwd: '/' })
+  await ctx.plugin(FsPolicy)
+  await ctx.plugin(ToolFs)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(ToolTodo)
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+  await ctx.plugin(ToolSubagent, { provider: 'spawn', toolName: 'subagent', enableRunInBackground: false })
+  await ctx.plugin(WorkerWorkflowEngine, { provider: 'spawn' })
+  await ctx.plugin(ToolWorkflow)
+  if (scenario.composition === 'code' || scenario.composition === 'advanced') {
+    await ctx.plugin(WorkerCodeRuntime, {})
+  }
+  if (scenario.composition === 'advanced') await ctx.plugin(ToolCordis, { vmTimeoutMs: 5_000 })
+  if (MODE === 'record' && scenario.recorded) {
+    await ctx.plugin(LlmDeepSeek)
+  } else {
+    installLlmReplay(ctx, { file: fixtureFile, childFiles, providers: PROVIDERS })
+  }
+  return ctx
+}
+
+interface ScenarioResult {
+  terminal: string
+  parent: Session
+  children: Session[]
+  workflowEvents: string[]
+}
+
+async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
+  const dir = scenarioDir(scenario)
+  const fixtureFile = join(dir, 'session.jsonl')
+  const childFiles = childFixturePaths(scenario)
+  const fixture = await readFile(fixtureFile, 'utf8')
+  const prompts = userPrompts(fixture)
+  expect(prompts.length, `${scenario.name} must carry at least one recorded user prompt`).toBeGreaterThan(0)
+
+  const cwd = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-snapshot-${scenario.name}-`))
+  let ctx: Context | undefined
+  let controller: ReturnType<typeof createTuiChat> | undefined
+  const terminal = new HeadlessTerminal(100, 36)
+  try {
+    if (scenario.seedWorkspace === true) {
+      const source = join(scenarioDir(scenario), 'workspace')
+      await cp(source, cwd, { recursive: true })
+    }
+    ctx = await mountScenarioContext(scenario, cwd, fixtureFile, childFiles)
+    const disposedSessions: Session[] = []
+    ctx.on('session/disposed', (session) => { disposedSessions.push(session) })
+    const workflowEvents: string[] = []
+    for (const name of ['workflow/start', 'workflow/phase', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) {
+      ctx.on(name, () => { workflowEvents.push(name) })
+    }
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('main-session'),
+      meta: { cwd },
+      agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    })
+    const agent: Agent = handle.agent
+    controller = createTuiChat(ctx, {
+      sessionId: 'main-session',
+      color: true,
+      showReasoning: true,
+      title: 'DSH TUI snapshot',
+      welcome: `Recorded replay: ${scenario.name}`,
+      maxToolOutputLines: 8,
+    }, { terminal, exit: () => {} })
+    await settleTerminal(terminal)
+
+    for (const prompt of prompts) {
+      terminal.send(prompt)
+      terminal.send('\r')
+      await agent.whenIdle()
+      await settleTerminal(terminal)
+    }
+
+    const events: SessionEvent[] = [...agent.session.events]
+    expect(events.filter(event => event.type === 'tool/call').map(event => event.data.name)).toEqual(scenario.expectedTools)
+    for (const [type, count] of Object.entries(scenario.expectedEventCounts ?? {})) {
+      expect(events.filter(event => event.type === type), `${scenario.name} must emit ${type}`).toHaveLength(count)
+    }
+    expect(events.filter(event => event.type === 'tool/result').every(event => !event.data.isError)).toBe(true)
+    expect(events.filter(event => event.type === 'turn/end').every(event => event.data.reason.kind !== 'error')).toBe(true)
+    if (scenario.name === 'dynamic-workflow' || scenario.name === 'cordis-dynamic-toolchain') {
+      expect(workflowEvents).toEqual([
+        'workflow/start',
+        'workflow/phase',
+        'workflow/agent-start',
+        'workflow/agent-end',
+        'workflow/end',
+      ])
+    }
+
+    expect(terminal.themeViolations(), `${scenario.name} must remain theme-agnostic`).toEqual([])
+    const snapshot = normalizeTerminalSnapshot(
+      await terminal.snapshot({ includeScrollback: true }),
+      cwd,
+    )
+    await handle.dispose()
+    const children = disposedSessions
+      .filter(session => session !== agent.session)
+      .sort((a, b) => a.header.createdAt - b.header.createdAt)
+    expect(children).toHaveLength(scenario.childSessions ?? 0)
+    return { terminal: snapshot, parent: agent.session, children, workflowEvents }
+  } finally {
+    await controller?.dispose()
+    await ctx?.fiber.dispose()
+    await terminal.dispose()
+    await rm(cwd, { recursive: true, force: true })
+  }
+}
+
+async function writeRecording(scenario: Scenario, result: ScenarioResult): Promise<void> {
+  const dir = scenarioDir(scenario)
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, 'session.jsonl'), scrubRequestHeaders(rawSessionLog(result.parent)))
+  expect(result.children).toHaveLength(scenario.childSessions ?? 0)
+  for (const [index, child] of result.children.entries()) {
+    await writeFile(join(dir, `session.${index + 1}.jsonl`), scrubRequestHeaders(rawSessionLog(child)))
+  }
+}
+
+describe('TUI recorded-session terminal snapshots', () => {
+  for (const scenario of SCENARIOS) {
+    it(scenario.name, async () => {
+      observedScenarios.add(scenario.name)
+      const result = await runScenario(scenario)
+      const terminalFile = join(scenarioDir(scenario), 'terminal.golden.txt')
+      if (MODE === 'record' || MODE === 'refresh') {
+        await mkdir(scenarioDir(scenario), { recursive: true })
+        await writeFile(terminalFile, result.terminal)
+      }
+      if (MODE === 'record' && scenario.recorded) await writeRecording(scenario, result)
+      await expect(result.terminal).toMatchFileSnapshot(terminalFile)
+    }, 120_000)
+  }
+})
+
+afterAll(async () => {
+  expect([...observedScenarios].sort()).toEqual(SCENARIOS.map(scenario => scenario.name).sort())
+  const directories = (await readdir(SNAPSHOTS_DIR, { withFileTypes: true }))
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort()
+  expect(directories).toEqual(SCENARIOS.map(scenario => scenario.name).sort())
+  for (const scenario of SCENARIOS) {
+    const expected = [
+      'session.jsonl',
+      'terminal.golden.txt',
+      ...scenario.seedWorkspace === true ? ['workspace'] : [],
+      ...Array.from({ length: scenario.childSessions ?? 0 }, (_, index) => `session.${index + 1}.jsonl`),
+    ].sort()
+    expect((await readdir(scenarioDir(scenario))).sort()).toEqual(expected)
+    for (const fixture of ['session.jsonl', ...childFixturePaths(scenario).map(path => basename(path))]) {
+      const content = await readFile(join(scenarioDir(scenario), fixture), 'utf8')
+      expect(scrubRequestHeaders(content), `${scenario.name}/${fixture} carries request-header bulk`).toBe(content)
+    }
+  }
+})
diff --git a/knip.json b/knip.json
index d64b8bb11b..0187d8e128 100644
--- a/knip.json
+++ b/knip.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "exclude": ["duplicates"],
-  "ignoreBinaries": ["bwrap", "sandbox-exec"],
+  "ignoreBinaries": ["bwrap", "python3", "sandbox-exec"],
   "ignoreWorkspaces": ["vendor/*", "python/sdk-runtime", "website"],
   "workspaces": {
     ".": {
@@ -10,6 +10,7 @@
     "examples": {
       "entry": [
         "echo-agent/src/*.ts",
+        "tui-agent/tests/fixtures/tui-scripted-llm.ts",
         "*/tests/**/*.e2e.ts",
         "*/tests/**/*.snapshot.ts"
       ],
@@ -117,6 +118,10 @@
       "entry": ["tests/**/*.spec.ts"],
       "project": ["src/**/*.ts", "tests/**/*.ts"]
     },
+    "packages/ui/tui": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.snapshot.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
     "packages/examples/jsonrpc-demo": {
       "project": ["src/**/*.ts"]
     },
diff --git a/package.json b/package.json
index 39d6a53161..ca85fd32d2 100644
--- a/package.json
+++ b/package.json
@@ -80,6 +80,7 @@
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
     "demo:echo": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml",
     "demo:repl": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/coding-agent/cordis.yml",
+    "demo:tui": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/tui-agent/cordis.yml",
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
     "demo:cordis": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/cordis-agent/cordis.yml",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index caaac783b6..01ce91a4e9 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -353,7 +353,7 @@ describe('compaction region transaction', () => {
   it('lands a framed, replayable checkpoint with exact pricing provenance', async () => {
     const compact = service()
     const session = conversation(3)
-    const before = session.surface.nodes
+    const before = [...session.surface.nodes]
     const result = await compact.compactRegion(
       before[0]!,
       before[3]!,
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 46b6ecb703..ba4e8ea94a 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -35,7 +35,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
 - `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
-- `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite.
+- `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
 - `session.seq`, `session.id` — current sequence and readonly typed identity.
 - `session.header: SessionHeader` — detached, deep-frozen creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Construction validates the durable record and requires its id to match `session.id`.
@@ -48,6 +48,7 @@ Durable values need one accepted representation, not a check followed by a secon
 
 - `SurfaceOp` — how an event entered the ordered surface: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace entries from `start` through `end` inclusive — both must be valid surface seqs; `start === end` replaces one entry). Used by compaction to shadow old events without deleting them.
 - `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types.
+- `SessionSurface` — the readonly live `nodes` and `replaceGeneration` projection exposed by `session.surface`; candidate validation remains private to `Session`.
 - `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface entry; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
 - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
 
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index ef84a6bfbc..b8b76ec2ed 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -16,13 +16,14 @@ import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
 import type { ContextEnvelope, CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
 import { SurfaceManager } from './surface.ts'
+import type { SessionSurface } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
 
 export * from './types.ts'
 export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
-export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
+export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
 export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
@@ -251,22 +252,12 @@ export function renderContextContent(
  */
 export class Session {
   private log: SessionEvent[] = []
-  /** Incremental acceptance state, kept separate from the public lazy view. */
-  private readonly surfaceValidator = new SurfaceManager(this.log)
-
-  /**
-   * Derived surface — a cached order of message-producing event sequences.
-   * Lazily rebuilt from `surfaceOp` markers in the log; processes only new
-   * events (delta) on each access — the log is append-only, so prior events
-   * never change.
-   * Undefined until first accessed (including after fork/seed).
-   */
-  private _surface: SurfaceManager | undefined
+  /** Single incremental owner of surface acceptance and projection state. */
+  private readonly surfaceManager = new SurfaceManager(this.log)
 
   /** The ordered surface over this session's event log. */
-  get surface(): SurfaceManager {
-    if (!this._surface) this._surface = new SurfaceManager(this.log)
-    return this._surface
+  get surface(): SessionSurface {
+    return this.surfaceManager
   }
 
   /**
@@ -309,7 +300,7 @@ export class Session {
         // live append and a full-log fold. The candidate is planned before it
         // enters `log`, so a failure cannot partially mutate the surface.
         try {
-          this.surfaceValidator.validateNext(snapshot)
+          this.surfaceManager.validateNext(snapshot)
         } catch (error: unknown) {
           throw new Error(`invalid seed event at index ${index}: ${error instanceof Error ? error.message : 'invalid surface metadata'}`)
         }
@@ -402,7 +393,7 @@ export class Session {
       data: dataSnapshot,
       ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
     } as unknown as SessionEvent<T>)
-    this.surfaceValidator.validateNext(event as SessionEvent)
+    this.surfaceManager.validateNext(event as SessionEvent)
 
     if (entry !== undefined) entry.appending = true
     try {
@@ -468,7 +459,7 @@ export class Session {
    *
    * CACHED: each surface node is projected exactly once, when first seen — a
    * call costs O(new nodes), and a surface rewrite (a `replace`;
-   * {@link SurfaceManager.replaceGeneration}) rebuilds. The returned array is
+   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
    * a fresh snapshot per call (later appends never grow an array a caller
    * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
    * Their content reuses the already frozen durable event data, so the cache
@@ -476,8 +467,9 @@ export class Session {
    * @returns a fresh array of the shared, frozen derived history.
    */
   deriveMessages(): Message[] {
-    const nodes = this.surface.nodes
-    const generation = this.surface.replaceGeneration
+    const surface = this.surface
+    const nodes = surface.nodes
+    const generation = surface.replaceGeneration
     if (generation !== this.derivedGeneration) {
       this.derived = []
       this.derivedNodes = 0
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index d4f43bc303..cf03ae685d 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -55,6 +55,14 @@ export interface SurfaceFoldResult {
   replacements: SurfaceFoldReplacement[]
 }
 
+/** Readonly live projection of the message-producing session events. */
+export interface SessionSurface {
+  /** Current surface event sequences in model-visible order. */
+  readonly nodes: readonly number[]
+  /** Monotonic count of committed positional replacements. */
+  readonly replaceGeneration: number
+}
+
 /** Mutable state shared by complete and incremental folds. */
 interface SurfaceFoldState {
   nodes: number[]
@@ -244,7 +252,7 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult
 }
 
 /** Incremental ordered surface view and append-boundary validator. */
-export class SurfaceManager {
+export class SurfaceManager implements SessionSurface {
   /** Shared transition state; replacement history is not retained. */
   private _state = createFoldState()
   /** Last processed seq; -1 folds a seeded log on first access. */
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index 16a74283be..3b15157bde 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -1,10 +1,18 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type { CreateSessionOptions, SessionEventType, SessionHeader, TodoItem } from '@deepseek-ai/dsh-session'
+import type { CreateSessionOptions, SessionEventType, SessionHeader, SessionSurface, TodoItem } from '@deepseek-ai/dsh-session'
 
 describe('Session', () => {
+  it('exposes one stable readonly surface view', () => {
+    const session = new Session(SessionId('surface-view'))
+    const surface = session.surface
+
+    expectTypeOf(surface).toEqualTypeOf<SessionSurface>()
+    expect(surface).toBe(session.surface)
+  })
+
   it('derives message history from the event log', () => {
     const session = new Session(SessionId('s1'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -1031,6 +1039,45 @@ describe('SessionStore', () => {
     expect(observed).toEqual([appended])
   })
 
+  it('does not publish a surface transition rejected by internal dispatch', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('surface-dispatch-veto'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'source' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const surface = session.surface
+    let reject = true
+    ctx.on('internal/dispatch', (_mode, name) => {
+      if (name === 'session/event' && reject) {
+        reject = false
+        throw new Error('reject surface candidate')
+      }
+    })
+
+    expect(() => session.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'mock' },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'replacement' }],
+    }, {
+      surfaceOp: { op: 'replace', start: 0, end: 0 },
+      sourceEventSeqs: [0],
+    })).toThrow('reject surface candidate')
+
+    expect(session.events).toHaveLength(1)
+    expect(surface.nodes).toEqual([0])
+    expect(surface.replaceGeneration).toBe(0)
+
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'next' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(surface.nodes).toEqual([0, 1])
+    expect(surface.replaceGeneration).toBe(0)
+  })
+
   it('resolves session/event dispatch before commit so instrumentation failure cannot hide a logged event', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index fe222f8f2f..d239533476 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -142,6 +142,11 @@ describe('SurfaceManager', () => {
   it('leaves incremental state unchanged when candidate validation fails', () => {
     const s = new Session(SessionId('atomic-validation'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const surface = s.surface
+    const nodes = surface.nodes
+
+    expect(nodes).toEqual(foldSurface(s.events).nodes)
+    expect(surface.replaceGeneration).toBe(0)
 
     expect(() => s.append(
       'assistant/message',
@@ -150,8 +155,16 @@ describe('SurfaceManager', () => {
     )).toThrow(/missing 0/)
 
     expect(s.events).toHaveLength(1)
+    expect(s.surface).toBe(surface)
+    expect(surface.nodes).toEqual([0])
+    expect(surface.replaceGeneration).toBe(0)
+    expect(surface.nodes).toEqual(foldSurface(s.events).nodes)
+
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(s.surface.nodes).toEqual([0, 1])
+    expect(surface.nodes).toBe(nodes)
+    expect(surface.nodes).toEqual([0, 1])
+    expect(surface.replaceGeneration).toBe(0)
+    expect(surface.nodes).toEqual(foldSurface(s.events).nodes)
   })
 
   it('foldSurface rejects a surface-eligible event without its mandatory marker', () => {
diff --git a/packages/examples/README.md b/packages/examples/README.md
index 994efbc02e..0135b730e2 100644
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -4,12 +4,12 @@ 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 + agent-execution + invariants + `tool-bash` + workspace-context + `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` |
+| `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` + workspace-context + `tool-skill` + `agent-loop`) |
+| `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.
 
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index c0dd79f037..794df27760 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -35,7 +35,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.
 
diff --git a/packages/examples/stdio-demo/README.md b/packages/examples/stdio-demo/README.md
index b783ca0078..ba4fc10101 100644
--- 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 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,12 +10,13 @@ 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 provider/model pair 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 exact app-owned agent/session identity and rendering it as `main` |
+| `@cordisjs/plugin-logger-console` | readline diagnostics for non-TTY operation; omitted from the fullscreen TUI path |
+| `@deepseek-ai/dsh-stdio` | the line-oriented channel for pipes and automation, bound to the exact app-owned agent/session identity |
+| `@deepseek-ai/dsh-tui` | the fullscreen interactive channel for TTY pairs, bound to the same exact identity |
 
 `@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`.
 
@@ -36,10 +37,11 @@ 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` | `{ mode: 'auto' }` | terminal mode (`auto` / `readline` / `tui`) and nested 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` and mint one combined `main-session-<uuid>` agent/session id, so durable restarts cannot collide. The app passes that exact opaque id to both its config-created agent and UI; an AgentLoop-only reload resumes materialized history under that id, while the UI's `main` text remains only a display label and never selects another registry root by prefix or insertion order. Readline buffers nonblank startup input for that identity until `agent/session-start`, so piped stdin cannot outrun asynchronous exact-id restoration or let EOF discard the queued prompt; `agent-loop/config-start-failed` instead drains and reports buffered input so a missing or corrupt persisted session cannot hang EOF. A resumed run binds both components to the exact `resumeSessionId` and keeps the cwd stored in the persisted session header.
+Fresh terminal sessions use the process launch directory as `session.header.cwd` and mint one combined `main-session-<uuid>` agent/session id, so durable restarts cannot collide. The app passes that exact opaque id to the config-created agent and selected UI before agent-core starts; this lets either front door observe `agent-loop/config-start-failed`, and an AgentLoop-only reload restores materialized history under the same id. Readline buffers startup input until `agent/session-start`; the TUI waits to enter fullscreen until the matching root appears. A resumed run binds both components to the exact `resumeSessionId` and keeps the persisted cwd.
 
 ## The bin
 
@@ -67,6 +69,8 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd` an
     provider: deepseek
     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".
@@ -75,9 +79,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. Terminal banners, logger output, cards, and rendered transcripts add zero model tokens.
 
 ### Human-answer result
 
@@ -87,6 +91,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 selected 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.
diff --git a/packages/examples/stdio-demo/package.json b/packages/examples/stdio-demo/package.json
index 992b63e1af..94554e3f8e 100644
--- 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,8 +32,8 @@
   "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-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
@@ -42,6 +42,7 @@
     "@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",
@@ -51,8 +52,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-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
@@ -62,6 +63,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:^",
diff --git a/packages/examples/stdio-demo/src/bin.ts b/packages/examples/stdio-demo/src/bin.ts
index 462e821e50..278bb5faca 100644
--- 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
  */
 
diff --git a/packages/examples/stdio-demo/src/index.ts b/packages/examples/stdio-demo/src/index.ts
index 0fb43cdff1..69a0be1171 100644
--- a/packages/examples/stdio-demo/src/index.ts
+++ b/packages/examples/stdio-demo/src/index.ts
@@ -1,9 +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
+ * coupled front-door cluster a terminal chat needs — TTY-selected pi-tui/readline
+ * presentation, JSONL session persistence, the user-interaction seam with its
  * `ask_user_question` tool, and one pre-created agent whose exact shared
- * agent/session identity the UI drives under its `main` display label.
+ * agent/session identity the selected UI drives under its `main` display label.
  * 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).
@@ -22,11 +22,46 @@ 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'
 const DEFAULT_PERSISTENCE_ROOT = './.sessions'
 const DEFAULT_WELCOME = 'ready.'
 
+/** 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 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. `provider`/`model`/`resumeSessionId` configure the pre-created `main` agent (through
@@ -35,7 +70,7 @@ const DEFAULT_WELCOME = 'ready.'
  * 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 {
   /** Provider route for the `main` agent. */
@@ -56,6 +91,8 @@ export interface Config {
   persistenceRoot?: string
   /** stdin-chat 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. */
@@ -85,6 +122,7 @@ export const Config: z<Config> = z.object({
   dshHome: z.string(),
   persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
   welcome: z.string().default(DEFAULT_WELCOME),
+  ui: UiConfigSchema,
   skills: agentCore.SkillConfigSchema,
   toolBash: agentCore.ToolBashConfigSchema,
   toolTasks: agentCore.ToolTasksConfigSchema,
@@ -93,23 +131,34 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * Compose the spine with the stdio front door. Console logging, persistence,
- * and user interaction mount first; the readline UI then waits on the agent
- * registry and subscribes to config-start failures before agent-core can start
- * the configured identity. The ask-user tool waits on the completed spine.
- * 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. Persistence and user
+ * interaction mount first; the selected UI then waits on the exact session id
+ * and subscribes to config-start failures before agent-core starts it. Console
+ * logging is readline-only because fullscreen output belongs to pi-tui. The
+ * ask-user tool waits on the completed spine, and HMR 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 process streams are interactive TTYs.
  */
-export function apply(ctx: Context, config: Config): void {
+export function composeTerminalApp(ctx: Context, config: Config, isTTY: boolean): void {
   const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
   const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
-  ctx.plugin(ConsoleExporter)
+  const mode = resolveTerminalMode(config.ui, isTTY)
+  if (mode === 'readline') ctx.plugin(ConsoleExporter)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT })
   ctx.plugin(UserInteractionService)
-  ctx.plugin(uiStdio, {
-    welcome: config.welcome ?? DEFAULT_WELCOME,
-    sessionId,
-  })
+  if (mode === 'tui') {
+    ctx.plugin(uiTui, {
+      ...config.ui?.tui,
+      welcome: config.welcome ?? DEFAULT_WELCOME,
+      sessionId,
+    })
+  } else {
+    ctx.plugin(uiStdio, {
+      welcome: config.welcome ?? DEFAULT_WELCOME,
+      sessionId,
+    })
+  }
   ctx.plugin(agentCore, {
     ...agentCore.pickSpineConfig(config),
     agents: [{
@@ -122,3 +171,11 @@ export function apply(ctx: Context, config: Config): void {
   })
   ctx.plugin(toolAskUser)
 }
+
+/** 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 */
diff --git a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
index 7ef169ff06..c8ca063151 100644
--- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
+++ b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
@@ -11,8 +11,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-spine-demo 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-spine-demo 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.
  */
@@ -66,6 +66,63 @@ 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('binds only the selected terminal package to the app-owned exact session identity', () => {
+    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, {
+      provider: 'mock',
+      model: 'mock',
+      workspaceContext: false,
+      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')
+    const tuiConfig = calls.find(call => call.name === 'ui-tui')?.config as { sessionId: string }
+    expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 })
+    expect(tuiConfig.sessionId).toMatch(/^main-session-/)
+    const spineConfig = calls.find(call => call.name === 'agent-spine-demo')?.config as {
+      agents: Array<{ id: string; sessionId?: string; resumeSessionId?: string }>
+    }
+    expect(spineConfig.agents[0]).toMatchObject({ id: 'main', sessionId: tuiConfig.sessionId })
+
+    calls.length = 0
+    stdioAgent.composeTerminalApp(ctx, {
+      provider: 'mock',
+      model: 'mock',
+      resumeSessionId: 'persisted-session',
+      workspaceContext: false,
+      ui: { mode: 'tui' },
+    }, true)
+    expect(calls.find(call => call.name === 'ui-tui')?.config).toMatchObject({
+      sessionId: 'persisted-session', welcome: 'ready.',
+    })
+    expect((calls.find(call => call.name === 'agent-spine-demo')?.config as typeof spineConfig).agents[0])
+      .toMatchObject({ id: 'main', resumeSessionId: 'persisted-session' })
+
+    calls.length = 0
+    stdioAgent.composeTerminalApp(ctx, {
+      provider: 'mock', model: 'mock', workspaceContext: false, 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({ provider: 'mock', model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
     // The spine services (brought up by the agent-spine-demo bundle) are all present.
diff --git a/packages/examples/stdio-demo/tsconfig.json b/packages/examples/stdio-demo/tsconfig.json
index be08d28f95..fc6711ffb9 100644
--- a/packages/examples/stdio-demo/tsconfig.json
+++ b/packages/examples/stdio-demo/tsconfig.json
@@ -41,6 +41,9 @@
     {
       "path": "../../ui/stdio"
     },
+    {
+      "path": "../../ui/tui"
+    },
     {
       "path": "../../ui/tool-ask-user"
     },
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index 62de4ffb08..9935233e85 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -12,6 +12,6 @@ The subagent seam: an agent delegating work to a child agent. Like the [bash](..
 | `subagent-acp/` | Out-of-process backend: a child agent in a spawned subprocess, driven over ACP | (registers on `ctx.subagents`) |
 | `tool-subagent/` | Model-facing `subagent` delegation tool over `ctx.subagents` | (registers on `ctx.tools`) |
 
-The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a library with no provider of its own — both depend on it, neither on the other), the out-of-process `subagent-acp` backend builds on the `subagent-subprocess` library (the credential env scrub, the dispose ladder, isolated config dirs) and ships alongside them here; the test-only `dsh-subagent-mock` (in [support](../support/README.md)) is separate. All **product** packages except the mock.
+The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a library with no provider of its own — both depend on it, neither on the other), and the out-of-process `subagent-acp` backend builds on the `subagent-subprocess` library (the credential env scrub, the dispose ladder, isolated config dirs). Tests replace only the child boundary with package-local fixtures.
 
 The proposal and design rationale: [docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md](../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md).
diff --git a/packages/subagent/tool-subagent/package.json b/packages/subagent/tool-subagent/package.json
index c52f5a74dc..e2d4378743 100644
--- a/packages/subagent/tool-subagent/package.json
+++ b/packages/subagent/tool-subagent/package.json
@@ -37,7 +37,6 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
-    "@deepseek-ai/dsh-subagent-mock": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
diff --git a/packages/subagent/tool-subagent/tests/scripted-provider.spec.ts b/packages/subagent/tool-subagent/tests/scripted-provider.spec.ts
new file mode 100644
index 0000000000..7365348410
--- /dev/null
+++ b/packages/subagent/tool-subagent/tests/scripted-provider.spec.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { type Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import * as scripted from './scripted-provider.ts'
+
+/** A minimal parent; the scripted provider only reads its id. */
+function fakeParent(id = 'parent-1'): Agent {
+  return { id: SessionId(id) } as unknown as Agent
+}
+
+function baseRequest(over: Partial<SubagentStartRequest> = {}): SubagentStartRequest {
+  return {
+    prompt: [{ type: 'text', text: 'task' }],
+    parent: fakeParent(),
+    signal: new AbortController().signal,
+    ...over,
+  }
+}
+
+async function mount(config: Partial<scripted.Config> = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SubagentService)
+  await scripted.mountScriptedProvider(ctx, { name: 'mock', ...config })
+  return ctx
+}
+
+describe('scripted subagent provider fixture', () => {
+  it('registers through the real service and returns the scripted reply', async () => {
+    const ctx = await mount({ reply: 'hello from fixture' })
+    expect(ctx.subagents.list()).toEqual(['mock'])
+
+    const run = await ctx.subagents.start('mock', baseRequest())
+    await expect(run.result).resolves.toEqual({
+      output: [{ type: 'text', text: 'hello from fixture' }],
+      structured: undefined,
+      stopReason: 'completed',
+    })
+    await run.dispose()
+  })
+
+  it('registers under a configurable name', async () => {
+    const ctx = await mount({ name: 'spawn' })
+    expect(ctx.subagents.list()).toEqual(['spawn'])
+  })
+
+  it('returns configured and default structured results', async () => {
+    const configured = await mount({ reply: 'r', structured: { answer: 42 } })
+    const schema = { type: 'object' as const, properties: { answer: { type: 'number' as const } } }
+    const configuredRun = await configured.subagents.start('mock', baseRequest({ outputSchema: schema }))
+    await expect(configuredRun.result).resolves.toMatchObject({ structured: { answer: 42 } })
+
+    const fallback = await mount({ reply: 'fallback reply' })
+    const fallbackRun = await fallback.subagents.start('mock', baseRequest({ outputSchema: schema }))
+    await expect(fallbackRun.result).resolves.toMatchObject({ structured: { reply: 'fallback reply' } })
+  })
+
+  it('omits structured output when no schema is requested', async () => {
+    const ctx = await mount({ capabilities: { outputSchema: false } })
+    const run = await ctx.subagents.start('mock', baseRequest())
+    expect(await run.result).not.toHaveProperty('structured')
+  })
+
+  it('honors configured and cancellation stop reasons', async () => {
+    const refused = await mount({ stopReason: 'refusal' })
+    const refusedRun = await refused.subagents.start('mock', baseRequest())
+    await expect(refusedRun.result).resolves.toMatchObject({ stopReason: 'refusal' })
+
+    const cancelled = await mount()
+    const controller = new AbortController()
+    const cancelledRun = await cancelled.subagents.start('mock', baseRequest({ signal: controller.signal }))
+    controller.abort()
+    await expect(cancelledRun.result).resolves.toMatchObject({ stopReason: 'aborted' })
+  })
+
+  it('rejects cancellation before or during asynchronous publication', async () => {
+    const ctx = await mount()
+    const alreadyAborted = new AbortController()
+    alreadyAborted.abort()
+    await expect(ctx.subagents.start('mock', baseRequest({ signal: alreadyAborted.signal })))
+      .rejects.toThrow('scripted subagent start aborted before publication')
+
+    const handoff = new AbortController()
+    const pending = ctx.subagents.start('mock', baseRequest({ signal: handoff.signal }))
+    handoff.abort()
+    await expect(pending).rejects.toThrow('scripted subagent start aborted before publication')
+  })
+
+  it('unregisters with its owning fixture fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const fiber = await scripted.mountScriptedProvider(ctx, { name: 'mock' })
+    expect(ctx.subagents.list()).toEqual(['mock'])
+    await fiber.dispose()
+    expect(ctx.subagents.list()).toEqual([])
+  })
+})
diff --git a/packages/subagent/tool-subagent/tests/scripted-provider.ts b/packages/subagent/tool-subagent/tests/scripted-provider.ts
new file mode 100644
index 0000000000..01c0769cf8
--- /dev/null
+++ b/packages/subagent/tool-subagent/tests/scripted-provider.ts
@@ -0,0 +1,104 @@
+/** Package-local scripted child boundary for deterministic tool-subagent tests. */
+
+import type { Context } from 'cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type {
+  SubagentCapabilities,
+  SubagentProvider,
+  SubagentResult,
+  SubagentRun,
+  SubagentStartRequest,
+  SubagentStopReason,
+} from '@deepseek-ai/dsh-subagent'
+
+const DEFAULT_CAPABILITIES: SubagentCapabilities = {
+  outputSchema: true,
+  depthLimit: true,
+  toolFilter: true,
+  persona: true,
+}
+
+/** Options for one scripted provider fixture. */
+export interface Config {
+  /** Registry name to register under. */
+  name: string
+  /** Final text returned by the scripted child. */
+  reply?: string
+  /** Terminal result reason. */
+  stopReason?: SubagentStopReason
+  /** Start-time features advertised by the provider. */
+  capabilities?: Partial<SubagentCapabilities>
+  /** Whether tool descriptions say the child inherits completed turns. */
+  inheritsParentContext?: boolean
+  /** Structured value returned when the request asks for one. */
+  structured?: unknown
+}
+
+/** Scripted provider whose result aborts if its signal or disposer wins first. */
+class ScriptedSubagentProvider implements SubagentProvider {
+  readonly capabilities: SubagentCapabilities
+  readonly inheritsParentContext: boolean
+
+  constructor(
+    readonly name: string,
+    private readonly config: Config,
+  ) {
+    this.capabilities = { ...DEFAULT_CAPABILITIES, ...config.capabilities }
+    this.inheritsParentContext = config.inheritsParentContext ?? false
+  }
+
+  async start(request: SubagentStartRequest): Promise<SubagentRun> {
+    if (request.signal.aborted) throw new Error('scripted subagent start aborted before publication')
+    const reply = this.config.reply ?? 'scripted subagent reply'
+    const output: ContentBlock[] = [{ type: 'text', text: reply }]
+    const wantsStructured = request.outputSchema !== undefined && this.capabilities.outputSchema
+    const stopReason = this.config.stopReason ?? 'completed'
+    const state = { cancelled: false }
+    const onAbort = (): void => { state.cancelled = true }
+    request.signal.addEventListener('abort', onAbort, { once: true })
+    await Promise.resolve()
+    if (state.cancelled) {
+      request.signal.removeEventListener('abort', onAbort)
+      throw new Error('scripted subagent start aborted before publication')
+    }
+
+    const resultFor = (): SubagentResult => ({
+      output,
+      ...wantsStructured ? { structured: this.config.structured ?? { reply } } : {},
+      stopReason: state.cancelled ? 'aborted' : stopReason,
+    })
+    const result = new Promise<SubagentResult>((resolve) => {
+      setTimeout(() => { resolve(resultFor()) }, 0)
+    }).finally(() => {
+      request.signal.removeEventListener('abort', onAbort)
+    })
+
+    return {
+      id: SessionId(`scripted-subagent:${this.name}:${request.parent.id}`),
+      localAgent: undefined,
+      result,
+      dispose(): Promise<void> {
+        state.cancelled = true
+        request.signal.removeEventListener('abort', onAbort)
+        return Promise.resolve()
+      },
+    }
+  }
+}
+
+/**
+ * Mount one scripted provider through an effect-scoped local plugin.
+ * @param ctx - context carrying the real subagent registry.
+ * @param config - scripted provider identity and outcome.
+ * @returns the fixture plugin's disposable fiber.
+ */
+export function mountScriptedProvider(ctx: Context, config: Config) {
+  return ctx.plugin({
+    name: 'scripted-subagent-provider',
+    inject: ['subagents'],
+    apply(pluginCtx: Context): void {
+      pluginCtx.subagents.registerProvider(new ScriptedSubagentProvider(config.name, config))
+    },
+  })
+}
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 3bd42ae299..d88367ced5 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -9,18 +9,17 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import TaskService from '@deepseek-ai/dsh-tasks'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
-import * as mock from '@deepseek-ai/dsh-subagent-mock'
+import * as mock from './scripted-provider.ts'
 import * as tool from '../src/index.ts'
 import { runOutcome, settleRun } from '../src/index.ts'
 import { SessionId } from '@deepseek-ai/dsh-session'
 
 /**
  * Drives the REAL plugin body: mounts `dsh-tool-subagent` on a real
- * `ToolRegistry` + `SubagentService`, with the real `dsh-subagent-mock` as the
- * backend, and invokes the registered `subagent` tool through
- * `ctx.tools.execute`. The mock is the genuine collaborator (we mock only the
- * "child agent", the expensive/non-deterministic boundary) — everything
- * downstream of the tool is the shipping code path.
+ * `ToolRegistry` + `SubagentService`, with a package-local scripted child
+ * boundary, and invokes the registered `subagent` tool through
+ * `ctx.tools.execute`. Everything downstream of the child boundary is the
+ * shipping code path.
  */
 
 /** A minimal parent Agent — the tool reads `agent.id` for `parent`. */
@@ -33,7 +32,7 @@ async function setup(toolConfig: tool.Config, mockConfig: Partial<mock.Config> =
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(SubagentService)
-  await ctx.plugin(mock, { name: 'mock', ...mockConfig })
+  await mock.mountScriptedProvider(ctx, { name: 'mock', ...mockConfig })
   await ctx.plugin(tool, toolConfig)
   return ctx
 }
@@ -131,8 +130,8 @@ describe('dsh-tool-subagent', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(SubagentService)
-    await ctx.plugin(mock, { name: 'spawn', reply: 'from spawn' })
-    await ctx.plugin(mock, { name: 'acp', reply: 'from acp' })
+    await mock.mountScriptedProvider(ctx, { name: 'spawn', reply: 'from spawn' })
+    await mock.mountScriptedProvider(ctx, { name: 'acp', reply: 'from acp' })
     await ctx.plugin(tool, { provider: 'spawn', toolName: 'subagent' })
     await ctx.plugin(tool, { provider: 'acp', toolName: 'subagent_acp' })
 
@@ -249,7 +248,7 @@ describe('dsh-tool-subagent', () => {
     tool.apply(ctx, { provider: 'mock' })
     expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(false)
     // Backend arrives (as a delayed sibling fiber would): the tool appears.
-    await ctx.plugin(mock, { name: 'mock', reply: 'late but fine' })
+    await mock.mountScriptedProvider(ctx, { name: 'mock', reply: 'late but fine' })
     expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
     const result = await callSubagent(ctx, { description: 'd', prompt: 'p' })
     expect(text(result)).toBe('late but fine')
@@ -260,7 +259,7 @@ describe('dsh-tool-subagent', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(SubagentService)
-    const backend = await ctx.plugin(mock, { name: 'mock' }) // fresh conversation (descriptor: false)
+    const backend = await mock.mountScriptedProvider(ctx, { name: 'mock' }) // fresh conversation (descriptor: false)
     await ctx.plugin(tool, { provider: 'mock' })
     expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('does not see this conversation')
 
@@ -270,7 +269,7 @@ describe('dsh-tool-subagent', () => {
 
     // Backend reloads with a DIFFERENT conversation-history descriptor: the wording is re-derived
     // from the fresh provider, not served stale from the first mount.
-    await ctx.plugin(mock, { name: 'mock', inheritsParentContext: true })
+    await mock.mountScriptedProvider(ctx, { name: 'mock', inheritsParentContext: true })
     expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('inherits this conversation')
   })
 
@@ -281,7 +280,7 @@ describe('dsh-tool-subagent', () => {
     await ctx.plugin(SubagentService)
 
     // Arm 1: a mounted tool dies with its plugin fiber; the provider survives.
-    await ctx.plugin(mock, { name: 'mock' })
+    await mock.mountScriptedProvider(ctx, { name: 'mock' })
     const mounted = await ctx.plugin(tool, { provider: 'mock' })
     expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
     await mounted.dispose()
@@ -293,7 +292,7 @@ describe('dsh-tool-subagent', () => {
     // live plugin owns (the zombie mount).
     const waiting = await ctx.plugin(tool, { provider: 'later', toolName: 'subagent_later' })
     await waiting.dispose()
-    await ctx.plugin(mock, { name: 'later' })
+    await mock.mountScriptedProvider(ctx, { name: 'later' })
     expect(ctx.tools.schemas().some(s => s.name === 'subagent_later')).toBe(false)
   })
 
@@ -302,11 +301,11 @@ describe('dsh-tool-subagent', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(SubagentService)
-    await ctx.plugin(mock, { name: 'mock' })
+    await mock.mountScriptedProvider(ctx, { name: 'mock' })
     await ctx.plugin(tool, { provider: 'mock' })
     // An unrelated provider registering (added-event with another name) and
     // unregistering (removed-event with another name) must not touch the tool.
-    const other = await ctx.plugin(mock, { name: 'other', inheritsParentContext: true })
+    const other = await mock.mountScriptedProvider(ctx, { name: 'other', inheritsParentContext: true })
     expect(ctx.tools.schemas().filter(s => s.name === 'subagent')).toHaveLength(1)
     expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('does not see this conversation')
     await other.dispose()
diff --git a/packages/support/README.md b/packages/support/README.md
index 0d991f07cf..433d6b3cdb 100644
--- a/packages/support/README.md
+++ b/packages/support/README.md
@@ -9,6 +9,5 @@ Packages that exist to serve development, testing, and the examples rather than
 | `invariants/` | Runtime event-contract assertions for development diagnostics | (listens on `session/*`, `agent/*`) |
 | `loader-smoke/` | Shared real-Loader subprocess harness for keyless example smokes | (library — imported by example e2e suites) |
 | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) |
-| `subagent-mock/` | Scripted `SubagentProvider` for deterministic seam/tool tests | (registers on `ctx.subagents`) |
 
-`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. `subagent-mock` exercises the real `ctx.subagents` load path without a model or child agent. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
+`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
diff --git a/packages/support/subagent-mock/README.md b/packages/support/subagent-mock/README.md
deleted file mode 100644
index a879433b67..0000000000
--- a/packages/support/subagent-mock/README.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# @deepseek-ai/dsh-subagent-mock
-
-A scripted `SubagentProvider` for testing the [subagent seam](../../subagent/subagent/README.md) without a model or a real child agent — the subagent analog of [`dsh-llm-replay`](../llm-replay/README.md).
-
-It lets a test drive `ctx.subagents` and the model-facing `dsh-tool-subagent` through the real Cordis loader/export path, exercising provider registration, async start, start-time capability validation, required-signal cancellation, `result`, `dispose`, and structured output deterministically and keylessly.
-
-## Usage
-
-Load it as a plugin (functional shape: `name`/`inject`/`Config`/`apply`, no default). Config (all optional):
-
-| Key | Default | Meaning |
-|---|---|---|
-| `name` | `mock` | Registry name to register the provider under. |
-| `reply` | `mock subagent reply` | The scripted child's final answer text. |
-| `stopReason` | `completed` | The stop reason `result` settles with. |
-| `capabilities` | all `true` | Which start-time capabilities (`outputSchema`, `depthLimit`, `toolFilter`, and `persona`) the provider advertises. |
-| `inheritsParentContext` | `false` | Conversation-history descriptor: `false` means fresh, while `true` exercises seeded/fork wording. It says nothing about tool, service, scope, or authority inheritance. |
-| `structured` | `{ reply }` | Structured value surfaced when a request carries an `outputSchema` and the capability is on. |
-
-Aborting the required request signal or disposing before `result` settles flips the stop reason to `aborted`, so both holder-facing cancellation paths are observable.
-
-## Model Experience
-
-Indirectly, through `dsh-tool-subagent`, which renders this test provider's configured reply or stop-reason error into the parent test history.
-
-## Known Limitations and Deferred Work
-
-- **Scripted provider only** — it does not run a model, create a child agent, or exercise real prompt/tool-loop behavior.
-- **One synthetic outcome per run** — it models no multi-turn, streaming, steering, resume, or subprocess transport behavior.
diff --git a/packages/support/subagent-mock/src/index.ts b/packages/support/subagent-mock/src/index.ts
deleted file mode 100644
index 4ea30d166a..0000000000
--- a/packages/support/subagent-mock/src/index.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-/**
- * Scripted, model-free subagent provider for deterministic coverage of registration,
- * capability checks, lifecycle, the model-facing tool, and structured results through the real
- * loader path. It is a named-export functional plugin; no default export.
- * @module @deepseek-ai/dsh-subagent-mock
- */
-
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import type {
-  SubagentCapabilities,
-  SubagentProvider,
-  SubagentResult,
-  SubagentRun,
-  SubagentStartRequest,
-  SubagentStopReason,
-} from '@deepseek-ai/dsh-subagent'
-
-const STOP_REASONS = ['completed', 'aborted', 'error', 'max-tokens', 'refusal'] as const
-
-const DEFAULT_CAPS: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true, persona: true }
-
-/** Scripted provider whose configured result aborts if disposed or signalled first. */
-class MockSubagentProvider implements SubagentProvider {
-  readonly capabilities: SubagentCapabilities
-  readonly inheritsParentContext: boolean
-
-  constructor(
-    readonly name: string,
-    private readonly config: Config,
-  ) {
-    this.capabilities = { ...DEFAULT_CAPS, ...config.capabilities }
-    this.inheritsParentContext = config.inheritsParentContext ?? false
-  }
-
-  async start(request: SubagentStartRequest): Promise<SubagentRun> {
-    if (request.signal.aborted) throw new Error('mock subagent start aborted before publication')
-    const reply = this.config.reply ?? 'mock subagent reply'
-    const output: ContentBlock[] = [{ type: 'text', text: reply }]
-    const wantsStructured = request.outputSchema !== undefined && this.capabilities.outputSchema
-    const baseStop: SubagentStopReason = this.config.stopReason ?? 'completed'
-    const flags = { cancelled: false }
-    const onAbort = (): void => { flags.cancelled = true }
-    request.signal.addEventListener('abort', onAbort, { once: true })
-    // Make publication genuinely asynchronous so a same-turn abort is still
-    // a provider-owned startup failure rather than a returned live run.
-    await Promise.resolve()
-    if (flags.cancelled) {
-      request.signal.removeEventListener('abort', onAbort)
-      throw new Error('mock subagent start aborted before publication')
-    }
-
-    // A deterministic child id derived from the parent — no clock/random (both
-    // banned in deterministic paths here, and unnecessary for a scripted run).
-    const id = SessionId(`mock-subagent:${this.name}:${request.parent.id}`)
-
-    const resultFor = (): SubagentResult => ({
-      output,
-      ...wantsStructured ? { structured: this.config.structured ?? { reply } } : {},
-      stopReason: flags.cancelled ? 'aborted' : baseStop,
-    })
-
-    const result = new Promise<SubagentResult>((resolve) => {
-      setTimeout(() => { resolve(resultFor()) }, 0)
-    }).finally(() => {
-      request.signal.removeEventListener('abort', onAbort)
-    })
-    return {
-      id,
-      localAgent: undefined,
-      result,
-      dispose(): Promise<void> {
-        flags.cancelled = true
-        request.signal.removeEventListener('abort', onAbort)
-        return Promise.resolve()
-      },
-    }
-  }
-}
-
-export const name = 'subagent-mock'
-export const inject = ['subagents']
-
-/** Config for the mock provider; all optional with test-friendly defaults. */
-export interface Config {
-  /** Registry name to register under. */
-  name: string
-  /** The text the scripted child "returns" as its final answer. */
-  reply?: string
-  /** The stop reason the run settles with. */
-  stopReason?: SubagentStopReason
-  /** Which start-time capabilities to advertise (default: all `true`). */
-  capabilities?: Partial<SubagentCapabilities>
-  /**
-   * The conversation-history descriptor to declare
-   * ({@link SubagentProvider.inheritsParentContext}); default `false` (fresh
-   * conversation). Set `true` to exercise seeded/fork wording in consumer
-   * tests. This flag says nothing about tool, service, scope, or authority
-   * inheritance.
-   */
-  inheritsParentContext?: boolean
-  /**
-   * Structured value surfaced when a request carries an `outputSchema` and the
-   * `outputSchema` capability is on (default: `{ reply }`).
-   */
-  structured?: unknown
-}
-
-export const Config: z<Config> = z.object({
-  name: z.string().default('mock'),
-  reply: z.string(),
-  stopReason: z.union(STOP_REASONS),
-  capabilities: z.object({
-    outputSchema: z.boolean(),
-    depthLimit: z.boolean(),
-    toolFilter: z.boolean(),
-    persona: z.boolean(),
-  }),
-  inheritsParentContext: z.boolean(),
-  structured: z.any(),
-})
-
-export function apply(ctx: Context, config: Config): void {
-  ctx.subagents.registerProvider(new MockSubagentProvider(config.name, config))
-}
diff --git a/packages/support/subagent-mock/tests/subagent-mock.spec.ts b/packages/support/subagent-mock/tests/subagent-mock.spec.ts
deleted file mode 100644
index aec0fd7db1..0000000000
--- a/packages/support/subagent-mock/tests/subagent-mock.spec.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import { type Agent } from '@deepseek-ai/dsh-agent'
-
-import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
-import * as mock from '../src/index.ts'
-import { SessionId } from '@deepseek-ai/dsh-session'
-
-/** A minimal parent — the mock provider only reads `parent.id`. */
-function fakeParent(id = 'parent-1'): Agent {
-  return { id: SessionId(id) } as unknown as Agent
-}
-
-function baseRequest(over: Partial<SubagentStartRequest> = {}): SubagentStartRequest {
-  return { prompt: [{ type: 'text', text: 'task' }], parent: fakeParent(), signal: new AbortController().signal, ...over }
-}
-
-async function mount(config: Partial<mock.Config> = {}): Promise<Context> {
-  const ctx = new Context()
-  await ctx.plugin(SubagentService)
-  await ctx.plugin(mock, { name: 'mock', ...config })
-  return ctx
-}
-
-describe('dsh-subagent-mock', () => {
-  it('registers a provider on ctx.subagents and returns the scripted reply', async () => {
-    const ctx = await mount({ reply: 'hello from mock' })
-    expect(ctx.subagents.list()).toEqual(['mock'])
-
-    const run = await ctx.subagents.start('mock', baseRequest())
-    await expect(run.result).resolves.toEqual({
-      output: [{ type: 'text', text: 'hello from mock' }],
-      structured: undefined,
-      stopReason: 'completed',
-    })
-    await run.dispose()
-  })
-
-  it('registers under a configurable name', async () => {
-    const ctx = await mount({ name: 'spawn' })
-    expect(ctx.subagents.list()).toEqual(['spawn'])
-  })
-
-  it('surfaces a structured result when the request carries an outputSchema', async () => {
-    const ctx = await mount({ reply: 'r', structured: { answer: 42 } })
-    const run = await ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
-    await expect(run.result).resolves.toMatchObject({ structured: { answer: 42 } })
-  })
-
-  it('defaults structured output to { reply } when outputSchema is requested but no structured value is configured', async () => {
-    const ctx = await mount({ reply: 'fallback reply' })
-    const run = await ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
-    await expect(run.result).resolves.toMatchObject({ structured: { reply: 'fallback reply' } })
-  })
-
-  it('omits structured output when outputSchema capability is off', async () => {
-    const ctx = await mount({ capabilities: { outputSchema: false } })
-    // The service rejects an outputSchema request against a no-cap provider, so
-    // the structured path is only reachable when the cap is on; with it off and
-    // no schema requested, the result has no structured field.
-    const run = await ctx.subagents.start('mock', baseRequest())
-    const result = await run.result
-    expect(result).not.toHaveProperty('structured')
-  })
-
-  it('honors a configured stop reason', async () => {
-    const ctx = await mount({ stopReason: 'refusal' })
-    const run = await ctx.subagents.start('mock', baseRequest())
-    await expect(run.result).resolves.toMatchObject({ stopReason: 'refusal' })
-  })
-
-  it('flips the stop reason to aborted when the signal fires before the result settles', async () => {
-    const ctx = await mount()
-    const controller = new AbortController()
-    const run = await ctx.subagents.start('mock', baseRequest({ signal: controller.signal }))
-    controller.abort()
-    await expect(run.result).resolves.toMatchObject({ stopReason: 'aborted' })
-  })
-
-  it('rejects an already-aborted request before starting publication', async () => {
-    const ctx = await mount()
-    const controller = new AbortController()
-    controller.abort()
-
-    await expect(ctx.subagents.start('mock', baseRequest({ signal: controller.signal })))
-      .rejects.toThrow('mock subagent start aborted before publication')
-  })
-
-  it('rejects when cancellation wins the asynchronous publication handoff', async () => {
-    const ctx = await mount()
-    const controller = new AbortController()
-    const pending = ctx.subagents.start('mock', baseRequest({ signal: controller.signal }))
-
-    controller.abort()
-
-    await expect(pending).rejects.toThrow('mock subagent start aborted before publication')
-  })
-
-  it('unregisters the provider when the owning fiber is disposed (HMR safety)', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SubagentService)
-    const fiber = await ctx.plugin(mock, { name: 'mock' })
-    expect(ctx.subagents.list()).toEqual(['mock'])
-    await fiber.dispose()
-    expect(ctx.subagents.list()).toEqual([])
-  })
-
-  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/Config/apply', () => {
-    // A default export would make Loader unwrap only that value and drop `inject`.
-    expect('default' in mock).toBe(false)
-    expect(mock.name).toBe('subagent-mock')
-    expect(mock.inject).toEqual(['subagents'])
-
-    const loader = Object.create(Loader.prototype) as Loader
-    const unwrapped = loader.unwrapExports(mock) as Record<string, unknown>
-    expect(unwrapped).toBe(mock)
-    expect(unwrapped.name).toBe('subagent-mock')
-    expect(unwrapped.inject).toEqual(['subagents'])
-    expect(typeof unwrapped.apply).toBe('function')
-  })
-})
diff --git a/packages/todo/README.md b/packages/todo/README.md
index b6a9ce2fc5..bfe5ec7503 100644
--- 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.
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 0b07539f3d..f6097abe96 100644
--- 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
 
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 699a11bdb4..3dd26d80a8 100644
--- 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.
diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md
index 403c91acd8..4e19313302 100644
--- 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
 
diff --git a/packages/ui/stdio/README.md b/packages/ui/stdio/README.md
index f9cebe11e6..caaa779c6e 100644
--- a/packages/ui/stdio/README.md
+++ b/packages/ui/stdio/README.md
@@ -11,7 +11,7 @@ This package owns the terminal channel only. It injects `agents` and `userIntera
 | `welcome` | `ready.` | Banner printed before the first prompt |
 | `sessionId` | `main` | Exact agent/session identity 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.
+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. While an initial exact identity is pending, it buffers nonblank input until `agent/session-start` and observes live `agent-loop/config-start-failed`; a matching failure drops queued lines, reports the loss, and lets piped EOF finish instead of hanging. The composing app must mount this front door before its config-created agent. Disposal closes readline and unregisters every listener/provider through Cordis effects.
 
 ```yaml
 - id: stdio
diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md
new file mode 100644
index 0000000000..e426640ae5
--- /dev/null
+++ b/packages/ui/tui/README.md
@@ -0,0 +1,64 @@
+# @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.
+
+The implemented [TUI feature RFC](../../../docs/rfc/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) owns the front-door decision; the [terminal-state snapshot RFC](../../../docs/rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns its verification strategy.
+
+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.
+
+Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling.
+
+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 |
+| `sessionId` | `main` | Exact shared agent/session identity 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 (see [Color](#color)) |
+| `title` | `DeepSeek Harness` | Terminal window title |
+
+```yaml
+- id: terminal
+  name: '@deepseek-ai/dsh-tui'
+  config:
+    welcome: 'Coding agent ready.'
+    sessionId: main-session-123
+    showReasoning: true
+    maxToolOutputLines: 12
+```
+
+Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. 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.
+
+## Color
+
+The palette uses the standard 16-color ANSI foregrounds and SGR attributes, which every terminal remaps to its active color scheme, so it stays readable on light and dark backgrounds alike. Body text keeps the terminal's default foreground rather than a fixed shade. Grouped regions (user prompts, tool cards) use a colored left-gutter bar instead of a filled background block, and the question overlay's active row uses reverse video; both are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling.
+
+## 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 session 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 `sessionId`.
+- **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.
diff --git a/packages/support/subagent-mock/package.json b/packages/ui/tui/package.json
similarity index 54%
rename from packages/support/subagent-mock/package.json
rename to packages/ui/tui/package.json
index c9d0982f55..fd4f187e35 100644
--- a/packages/support/subagent-mock/package.json
+++ b/packages/ui/tui/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@deepseek-ai/dsh-subagent-mock",
-  "description": "Scripted subagent provider for testing the subagent seam (keyless, deterministic)",
+  "name": "@deepseek-ai/dsh-tui",
+  "description": "Interactive pi-tui terminal front door for DeepSeek Harness agents",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -23,20 +23,30 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "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-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-subagent": "workspace:^",
-    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tool-cordis": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-workflow": "workspace:^",
+    "@xterm/headless": "5.5.0",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
new file mode 100644
index 0000000000..0906b7bc9f
--- /dev/null
+++ b/packages/ui/tui/src/index.ts
@@ -0,0 +1,1355 @@
+/**
+ * Interactive pi-tui front door for DeepSeek Harness agents. It renders the
+ * durable session transcript, drives one configured agent, and provides
+ * keyboard-driven user-interaction dialogs without owning agent lifecycle.
+ * @module @deepseek-ai/dsh-tui
+ */
+
+import { homedir } from 'node:os'
+import { relative, resolve, sep } from 'node:path'
+import {
+  CombinedAutocompleteProvider,
+  Container,
+  Editor,
+  Input,
+  Key,
+  Loader,
+  Markdown,
+  Spacer,
+  Text,
+  TUI,
+  ProcessTerminal,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Component,
+  type EditorTheme,
+  type Focusable,
+  type MarkdownTheme,
+  type OverlayHandle,
+  type SelectListTheme,
+  type Terminal,
+} from '@earendil-works/pi-tui'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent-loop'
+import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session'
+import type {
+  FileDiff,
+  TerminalCallView,
+  ToolCallView,
+  ToolDefinition,
+  ToolResultView,
+} from '@deepseek-ai/dsh-tools'
+import {
+  UserInteractionError,
+  type AskUserQuestionAnswer,
+  type AskUserQuestionAnswerItem,
+  type AskUserQuestionItem,
+  type AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-interaction'
+
+export const name = 'ui-tui'
+export const inject = ['agents', 'userInteraction', 'tools']
+
+/** Presentation settings for the pi-tui terminal mode. */
+export interface TuiConfig {
+  /** Render model reasoning blocks. */
+  showReasoning?: boolean
+  /** Maximum tool-output lines shown before the card is collapsed. */
+  maxToolOutputLines?: number
+  /** Maximum options visible at once in a user-question dialog. */
+  maxQuestionOptions?: number
+  /** User-question dialog width in terminal columns. */
+  questionDialogWidth?: number
+  /** User-question dialog maximum height in terminal rows. */
+  questionDialogMaxHeight?: number
+  /** Show the terminal's hardware cursor at the pi editor's IME marker. */
+  showHardwareCursor?: boolean
+  /** Apply the built-in ANSI color palette. */
+  color?: boolean
+  /** Terminal window title while the UI is mounted. */
+  title?: string
+}
+
+const showReasoningSchema = z.boolean().default(true)
+const maxToolOutputLinesSchema = z.number().step(1).min(1).default(12)
+const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
+const questionDialogWidthSchema = z.number().step(1).min(20).default(72)
+const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
+const showHardwareCursorSchema = z.boolean().default(false)
+const colorSchema = z.boolean().default(true)
+const titleSchema = z.string().default('DeepSeek Harness')
+
+/** Schemastery schema for presentation settings embedded by app bundles. */
+export const TuiConfigSchema: z<TuiConfig> = z.object({
+  showReasoning: showReasoningSchema,
+  maxToolOutputLines: maxToolOutputLinesSchema,
+  maxQuestionOptions: maxQuestionOptionsSchema,
+  questionDialogWidth: questionDialogWidthSchema,
+  questionDialogMaxHeight: questionDialogMaxHeightSchema,
+  showHardwareCursor: showHardwareCursorSchema,
+  color: colorSchema,
+  title: titleSchema,
+})
+
+/** Serializable plugin configuration. */
+export interface Config extends TuiConfig {
+  /** Header subtitle. Defaults to `ready.`. */
+  welcome?: string
+  /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
+  sessionId?: string
+}
+
+export const Config: z<Config> = z.object({
+  welcome: z.string().default('ready.'),
+  sessionId: z.string().default('main'),
+  showReasoning: showReasoningSchema,
+  maxToolOutputLines: maxToolOutputLinesSchema,
+  maxQuestionOptions: maxQuestionOptionsSchema,
+  questionDialogWidth: questionDialogWidthSchema,
+  questionDialogMaxHeight: questionDialogMaxHeightSchema,
+  showHardwareCursor: showHardwareCursorSchema,
+  color: colorSchema,
+  title: titleSchema,
+})
+
+/** Fully defaulted TUI presentation settings. */
+export interface ResolvedTuiConfig {
+  showReasoning: boolean
+  maxToolOutputLines: number
+  maxQuestionOptions: number
+  questionDialogWidth: number
+  questionDialogMaxHeight: number
+  showHardwareCursor: boolean
+  color: boolean
+  title: string
+}
+
+/** Runtime boundary used by the interactive TUI. */
+export interface TuiRuntime {
+  /** Terminal implementation; production uses pi-tui's `ProcessTerminal`. */
+  terminal: Terminal
+  /** Exit hook used by terminal shutdown or a target-agent startup failure. */
+  exit(code: number): void
+}
+
+/**
+ * Apply direct-call defaults after Loader schema validation has normally run.
+ *
+ * @param config - Deployment-provided terminal presentation settings.
+ * @returns Complete settings consumed by the TUI renderer.
+ */
+export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConfig {
+  return {
+    showReasoning: config?.showReasoning ?? true,
+    maxToolOutputLines: config?.maxToolOutputLines ?? 12,
+    maxQuestionOptions: config?.maxQuestionOptions ?? 8,
+    questionDialogWidth: config?.questionDialogWidth ?? 72,
+    questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
+    showHardwareCursor: config?.showHardwareCursor ?? false,
+    color: config?.color ?? true,
+    title: config?.title ?? 'DeepSeek Harness',
+  }
+}
+
+interface Palette {
+  accent: (text: string) => string
+  accent2: (text: string) => string
+  text: (text: string) => string
+  muted: (text: string) => string
+  dim: (text: string) => string
+  success: (text: string) => string
+  warning: (text: string) => string
+  error: (text: string) => string
+  code: (text: string) => string
+  added: (text: string) => string
+  removed: (text: string) => string
+  bold: (text: string) => string
+  italic: (text: string) => string
+  underline: (text: string) => string
+  strike: (text: string) => string
+  /** Reverse video for the active selection; swaps the theme's own fg/bg so it reads on any scheme. */
+  selected: (text: string) => string
+}
+
+function ansi(open: string, close: string, enabled: boolean): (text: string) => string {
+  return enabled ? text => `\x1b[${open}m${text}\x1b[${close}m` : text => text
+}
+
+const TERMINAL_CONTROL_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/gu
+
+/**
+ * Escape external C0/C1 controls before pi-tui adds application-owned ANSI.
+ * Line feeds remain structural so transcript and tool output retain their layout.
+ */
+function displayText(text: string): string {
+  return text.replace(TERMINAL_CONTROL_PATTERN, control =>
+    `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`)
+}
+
+/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */
+function renderThrown(value: unknown): string {
+  try {
+    return String(value)
+  } catch {
+    return '<unrenderable thrown value>'
+  }
+}
+
+/**
+ * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR
+ * attributes, which every terminal remaps to its active color scheme. Body
+ * `text` stays the terminal's default foreground so it reads on light and dark
+ * backgrounds alike; grouping uses foreground-only gutter bars and reverse
+ * video rather than fixed background fills.
+ */
+function createPalette(enabled: boolean): Palette {
+  return {
+    accent: ansi('94', '39', enabled),
+    accent2: ansi('95', '39', enabled),
+    text: text => text,
+    muted: ansi('90', '39', enabled),
+    dim: ansi('2', '22', enabled),
+    success: ansi('32', '39', enabled),
+    warning: ansi('33', '39', enabled),
+    error: ansi('31', '39', enabled),
+    code: ansi('36', '39', enabled),
+    added: ansi('32', '39', enabled),
+    removed: ansi('31', '39', enabled),
+    bold: ansi('1', '22', enabled),
+    italic: ansi('3', '23', enabled),
+    underline: ansi('4', '24', enabled),
+    strike: ansi('9', '29', enabled),
+    selected: ansi('7', '27', enabled),
+  }
+}
+
+function markdownTheme(palette: Palette): MarkdownTheme {
+  return {
+    heading: text => palette.accent(text),
+    link: text => palette.accent(text),
+    // pi-tui requires this URL slot but its current Markdown renderer does not invoke it.
+    /* v8 ignore next */
+    linkUrl: text => palette.dim(text),
+    code: text => palette.code(text),
+    codeBlock: text => palette.text(text),
+    codeBlockBorder: text => palette.dim(text),
+    quote: text => palette.muted(text),
+    quoteBorder: text => palette.accent2(text),
+    hr: text => palette.dim(text),
+    listBullet: text => palette.accent(text),
+    bold: text => palette.bold(text),
+    italic: text => palette.italic(text),
+    strikethrough: text => palette.strike(text),
+    underline: text => palette.underline(text),
+  }
+}
+
+function selectTheme(palette: Palette): SelectListTheme {
+  return {
+    selectedPrefix: palette.accent,
+    selectedText: palette.accent,
+    description: palette.muted,
+    scrollInfo: palette.dim,
+    noMatch: palette.warning,
+  }
+}
+
+function contentText(content: readonly ContentBlock[]): string {
+  const parts: string[] = []
+  for (const block of content) {
+    switch (block.type) {
+      case 'text':
+      case 'reasoning':
+        parts.push(block.text)
+        break
+      case 'tool-call':
+        parts.push(`${block.name}(${block.arguments})`)
+        break
+      case 'tool-result':
+        parts.push(contentText(block.content))
+        break
+      default: {
+        const rawType = (block as { type?: unknown }).type
+        parts.push(`[${typeof rawType === 'string' ? rawType : 'content'}]`)
+        break
+      }
+    }
+  }
+  return parts.join('')
+}
+
+function textBlocks(content: readonly ContentBlock[], type: 'text' | 'reasoning'): string {
+  return content
+    .filter((block): block is Extract<ContentBlock, { type: typeof type }> => block.type === type)
+    .map(block => block.text)
+    .join('\n\n')
+}
+
+class HeaderComponent implements Component {
+  constructor(
+    private readonly agent: Agent,
+    private readonly welcome: string,
+    private readonly palette: Palette,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const usable = Math.max(1, width - 4)
+    const title = `${this.palette.bold(this.palette.accent('DEEPSEEK'))} ${this.palette.bold('HARNESS')}`
+    const model = displayText(this.agent.options.model ?? 'model unset')
+    const detail = `${model}  •  ${displayText(this.agent.session.id)}`
+    const top = this.palette.accent(`╭${'─'.repeat(Math.max(0, width - 2))}╮`)
+    const bottom = this.palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`)
+    const lines = [title, this.palette.muted(displayText(this.welcome)), this.palette.dim(detail)]
+      .flatMap(line => wrapTextWithAnsi(line, usable))
+      .map((line) => {
+        const clipped = truncateToWidth(line, usable, '')
+        return `${this.palette.accent('│')} ${clipped}${' '.repeat(Math.max(0, usable - visibleWidth(clipped)))} ${this.palette.accent('│')}`
+      })
+    return [top, ...lines, bottom]
+  }
+}
+
+/**
+ * Groups children behind a colored left-gutter bar (`▌`). Foreground-only, so
+ * it renders legibly on any terminal background — unlike a filled block whose
+ * body text would collide with the theme's default foreground.
+ */
+class GutterBox implements Component {
+  protected readonly children: Component[] = []
+
+  constructor(private readonly barFn: (text: string) => string, private readonly paddingY = 1) {}
+
+  addChild(child: Component): void {
+    this.children.push(child)
+  }
+
+  invalidate(): void {
+    for (const child of this.children) child.invalidate()
+  }
+
+  render(width: number): string[] {
+    const inner = Math.max(1, width - 2)
+    const body: string[] = []
+    for (const child of this.children) for (const line of child.render(inner)) body.push(line)
+    // Every caller adds a non-empty title/label child, so an all-empty box is unreachable;
+    // the guard preserves Box semantics (render nothing) rather than emitting stray gutter bars.
+    /* v8 ignore next */
+    if (body.length === 0) return []
+    const bar = this.barFn('▌')
+    const pad = Array.from({ length: this.paddingY }, () => '')
+    return [...pad, ...body, ...pad].map(line => `${bar} ${line}`)
+  }
+}
+
+class UserMessageComponent extends GutterBox {
+  constructor(text: string, palette: Palette, mdTheme: MarkdownTheme, label = 'You') {
+    super(value => palette.accent(value))
+    this.addChild(new Text(palette.bold(palette.accent(displayText(label))), 0, 0))
+    this.addChild(new Markdown(displayText(text), 0, 0, mdTheme, { color: value => palette.text(value) }, {
+      preserveOrderedListMarkers: true,
+      preserveBackslashEscapes: true,
+    }))
+  }
+}
+
+class AssistantMessageComponent extends Container {
+  constructor(content: readonly ContentBlock[], showReasoning: boolean, palette: Palette, mdTheme: MarkdownTheme) {
+    super()
+    const reasoning = displayText(textBlocks(content, 'reasoning').trim())
+    const text = displayText(textBlocks(content, 'text').trim())
+    if (reasoning && showReasoning) {
+      this.addChild(new Spacer(1))
+      this.addChild(new Text(palette.italic(palette.muted('Reasoning')), 1, 0))
+      this.addChild(new Markdown(reasoning, 1, 0, mdTheme, {
+        color: value => palette.muted(value),
+        italic: true,
+      }))
+    }
+    if (text) {
+      this.addChild(new Spacer(1))
+      this.addChild(new Text(palette.bold(palette.accent2('Assistant')), 1, 0))
+      this.addChild(new Markdown(text, 1, 0, mdTheme, { color: value => palette.text(value) }))
+    }
+  }
+}
+
+interface StreamingBlock {
+  type: string
+  text: string
+}
+
+class StreamingAssistantComponent extends Container {
+  private readonly blocks = new Map<number, StreamingBlock>()
+
+  constructor(
+    private showReasoning: boolean,
+    private readonly palette: Palette,
+    private readonly mdTheme: MarkdownTheme,
+  ) {
+    super()
+  }
+
+  update(chunk: StreamChunk): void {
+    if (chunk.type === 'block-start') {
+      this.blocks.set(chunk.index, { type: chunk.blockType, text: '' })
+    } else if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
+      const type = chunk.type === 'text-delta' ? 'text' : 'reasoning'
+      const block = this.blocks.get(chunk.index) ?? { type, text: '' }
+      block.text += chunk.text
+      this.blocks.set(chunk.index, block)
+    } else if (chunk.type === 'block-end' && (chunk.block.type === 'text' || chunk.block.type === 'reasoning')) {
+      this.blocks.set(chunk.index, { type: chunk.block.type, text: chunk.block.text })
+    }
+    this.rebuild()
+  }
+
+  setShowReasoning(show: boolean): void {
+    this.showReasoning = show
+    this.rebuild()
+  }
+
+  private rebuild(): void {
+    this.clear()
+    const content: ContentBlock[] = [...this.blocks.entries()]
+      .sort(([left], [right]) => left - right)
+      .flatMap<ContentBlock>(([, block]) => {
+        if (block.type === 'text') return [{ type: 'text', text: block.text }]
+        if (block.type === 'reasoning') return [{ type: 'reasoning', text: block.text }]
+        return []
+      })
+    const component = new AssistantMessageComponent(content, this.showReasoning, this.palette, this.mdTheme)
+    for (const child of component.children) this.addChild(child)
+  }
+}
+
+interface ParsedArguments {
+  value: unknown
+  valid: boolean
+}
+
+function parseArguments(raw: string): ParsedArguments {
+  try {
+    return { value: JSON.parse(raw), valid: true }
+  } catch {
+    return { value: raw, valid: false }
+  }
+}
+
+function pretty(value: unknown): string {
+  if (typeof value === 'string') return displayText(value)
+  // The lib declaration narrows `unknown` to a string-returning overload, but
+  // JSON.stringify returns undefined for runtime values such as symbols.
+  const serialized = JSON.stringify(value, null, 2) as string | undefined
+  return displayText(serialized ?? String(value))
+}
+
+function diffLines(diff: FileDiff, palette: Palette): string[] {
+  const lines = [palette.bold(displayText(diff.path))]
+  if (diff.oldText !== null) {
+    for (const line of displayText(diff.oldText).split('\n')) lines.push(palette.removed(`- ${line}`))
+  }
+  for (const line of displayText(diff.newText).split('\n')) lines.push(palette.added(`+ ${line}`))
+  return lines
+}
+
+class ToolCardComponent implements Component {
+  private result: { content: ContentBlock[]; isError: boolean; meta?: unknown } | undefined
+  private expanded = false
+  private callView: ToolCallView
+  private resultView: ToolResultView | undefined
+
+  constructor(
+    private readonly name: string,
+    private readonly parsed: ParsedArguments,
+    private readonly definition: ToolDefinition | undefined,
+    private readonly maxOutputLines: number,
+    private readonly palette: Palette,
+  ) {
+    this.callView = this.presentCall()
+  }
+
+  private presentCall(): ToolCallView {
+    if (this.parsed.valid && this.definition?.presentCall) {
+      try {
+        const view = this.definition.presentCall(this.parsed.value)
+        if (view !== undefined) return view
+      } catch (error: unknown) {
+        return { card: 'generic', title: displayText(this.name), rawInput: `Presenter failed: ${String(error)}` }
+      }
+    }
+    return { card: 'generic', title: displayText(this.name), rawInput: this.parsed.value }
+  }
+
+  updateResult(event: Extract<SessionEvent, { type: 'tool/result' }>['data']): void {
+    this.result = {
+      content: [...event.content],
+      isError: event.isError,
+      ...event.meta !== undefined ? { meta: event.meta } : {},
+    }
+    if (this.parsed.valid && this.definition?.presentResult) {
+      try {
+        const view = this.definition.presentResult(this.parsed.value, this.result)
+        if (view !== undefined) this.resultView = view
+      } catch (error: unknown) {
+        this.resultView = { card: 'generic', content: [{ type: 'text', text: `Presenter failed: ${String(error)}` }] }
+      }
+    }
+  }
+
+  setExpanded(expanded: boolean): void {
+    this.expanded = expanded
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const isError = this.result?.isError ?? false
+    const glyph = this.result === undefined ? this.palette.warning('◌') : isError ? this.palette.error('✕') : this.palette.success('✓')
+    const body = this.renderBody()
+    const title = truncateToWidth(`${glyph} ${displayText(this.title())}`, Math.max(1, width - 4), '')
+    const visibleBody = this.expanded || body.length <= this.maxOutputLines
+      ? body
+      : [...body.slice(0, this.maxOutputLines), this.palette.dim(`… ${body.length - this.maxOutputLines} more lines (Ctrl+O to expand)`)]
+    const barFn = this.result === undefined
+      ? this.palette.warning
+      : isError ? this.palette.error : this.palette.success
+    const box = new GutterBox(barFn, visibleBody.length > 0 ? 1 : 0)
+    box.addChild(new Text(this.palette.bold(title), 0, 0))
+    if (visibleBody.length > 0) box.addChild(new Text(visibleBody.join('\n'), 0, 0))
+    return box.render(width)
+  }
+
+  private title(): string {
+    return this.resultView?.title ?? this.callView.title
+  }
+
+  private renderBody(): string[] {
+    const view = this.resultView ?? this.callView
+    if (view.card === 'terminal') {
+      const pending = this.callView.card === 'terminal' ? this.callView : undefined
+      const lines: string[] = []
+      if (pending?.description) lines.push(this.palette.muted(displayText(pending.description)))
+      if (pending?.cwd) lines.push(this.palette.dim(displayText(pending.cwd)))
+      if (this.resultView?.card === 'terminal') {
+        if (this.resultView.output) lines.push(...displayText(this.resultView.output).split('\n'))
+        if (this.resultView.exitCode !== undefined) lines.push(this.palette.dim(`[exit ${this.resultView.exitCode}]`))
+        if (this.resultView.signal !== undefined) {
+          lines.push(this.palette.error(`[signal ${displayText(this.resultView.signal)}]`))
+        }
+      } else if (this.result === undefined) {
+        // A pending terminal view is the call view itself; TerminalCallView requires a title.
+        lines.push(this.palette.code(`$ ${displayText((pending as TerminalCallView).title)}`))
+      } else {
+        lines.push(...displayText(contentText(this.result.content)).split('\n'))
+      }
+      return lines.filter(Boolean)
+    }
+    if (view.card === 'diff') {
+      return view.diffs.flatMap((diff, index) => [
+        ...index > 0 ? [''] : [],
+        ...diffLines(diff, this.palette),
+      ])
+    }
+    const content = view.content ?? this.result?.content
+    const lines: string[] = []
+    if (content !== undefined) lines.push(...displayText(contentText(content)).split('\n'))
+    const rawInput = this.result === undefined && this.callView.card === 'generic'
+      ? this.callView.rawInput
+      : undefined
+    if (rawInput !== undefined) lines.push(...pretty(rawInput).split('\n'))
+    return lines.filter((line, index, all) => line.length > 0 || (index > 0 && index < all.length - 1))
+  }
+}
+
+class TodoComponent implements Component {
+  private todos: readonly TodoItem[] = []
+
+  constructor(private readonly palette: Palette) {}
+
+  update(todos: readonly TodoItem[]): void {
+    this.todos = todos
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    if (this.todos.length === 0) return []
+    const lines = [this.palette.bold(this.palette.accent('Plan'))]
+    for (const todo of this.todos) {
+      const prefix = todo.status === 'completed'
+        ? this.palette.success('✓')
+        : todo.status === 'in_progress'
+          ? this.palette.warning('●')
+          : this.palette.dim('○')
+      const content = displayText(todo.content)
+      const text = todo.status === 'completed' ? this.palette.muted(content) : content
+      lines.push(truncateToWidth(`  ${prefix} ${text}`, width, ''))
+    }
+    return ['', ...lines]
+  }
+}
+
+function formatTokens(value: number): string {
+  if (value < 1_000) return String(value)
+  if (value < 10_000) return `${(value / 1_000).toFixed(1)}k`
+  if (value < 1_000_000) return `${Math.round(value / 1_000)}k`
+  return `${(value / 1_000_000).toFixed(1)}m`
+}
+
+function formatCwd(cwd: string | undefined): string {
+  if (cwd === undefined) return 'cwd unset'
+  const home = homedir()
+  const rel = relative(resolve(home), resolve(cwd))
+  if (rel === '') return '~'
+  if (rel !== '..' && !rel.startsWith(`..${sep}`)) return displayText(`~${sep}${rel}`)
+  return displayText(cwd)
+}
+
+function sessionTokens(session: Session): { input: number; output: number } {
+  let input = 0
+  let output = 0
+  for (const event of session.events) {
+    if (event.type !== 'assistant/message' || event.data.usage === undefined) continue
+    input += event.data.usage.inputTokens
+    output += event.data.usage.outputTokens
+  }
+  return { input, output }
+}
+
+class FooterComponent implements Component {
+  constructor(
+    private readonly agent: Agent,
+    private readonly palette: Palette,
+    private readonly toolsExpanded: () => boolean,
+    private readonly showReasoning: () => boolean,
+    private readonly tokens: () => { input: number; output: number },
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const { input, output } = this.tokens()
+    const left = `${formatCwd(this.agent.session.header.cwd)}  ↑${formatTokens(input)} ↓${formatTokens(output)}`
+    const right = `${this.agent.status}  reasoning:${this.showReasoning() ? 'on' : 'off'}  tools:${this.toolsExpanded() ? 'expanded' : 'compact'}`
+    const leftStyled = this.palette.dim(left)
+    const available = Math.max(0, width - visibleWidth(left) - 2)
+    const rightClipped = truncateToWidth(right, available, '')
+    const gap = ' '.repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(rightClipped)))
+    return [truncateToWidth(`${leftStyled}${gap}${this.palette.dim(rightClipped)}`, width, '')]
+  }
+}
+
+interface QuestionSelection {
+  selected: string[]
+  custom?: string
+}
+
+class QuestionDialog implements Component, Focusable {
+  private selectedIndex = 0
+  private selected = new Set<number>()
+  private mode: 'options' | 'custom'
+  private error = ''
+  private readonly input = new Input()
+  private readonly options: NonNullable<AskUserQuestionItem['options']>
+  focused = false
+
+  constructor(
+    private readonly question: AskUserQuestionItem,
+    private readonly maxVisible: number,
+    private readonly palette: Palette,
+    private readonly done: (selection: QuestionSelection) => void,
+    private readonly cancel: () => void,
+  ) {
+    this.options = question.options ?? []
+    this.mode = this.options.length > 0 ? 'options' : 'custom'
+    this.input.onSubmit = (value) => { this.submitCustom(value) }
+    this.input.onEscape = () => {
+      if (this.options.length > 0) {
+        this.mode = 'options'
+        this.error = ''
+      } else {
+        this.cancel()
+      }
+    }
+  }
+
+  invalidate(): void {
+    this.input.invalidate()
+  }
+
+  handleInput(data: string): void {
+    this.invalidate()
+    if (this.mode === 'custom') {
+      this.input.focused = this.focused
+      this.input.handleInput(data)
+      return
+    }
+    const options = this.options
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = this.selectedIndex === 0 ? options.length - 1 : this.selectedIndex - 1
+    } else if (matchesKey(data, Key.down)) {
+      this.selectedIndex = this.selectedIndex === options.length - 1 ? 0 : this.selectedIndex + 1
+    } else if (matchesKey(data, Key.space) && this.question.multiSelect) {
+      if (this.selected.has(this.selectedIndex)) this.selected.delete(this.selectedIndex)
+      else this.selected.add(this.selectedIndex)
+    } else if (matchesKey(data, Key.enter)) {
+      const indices = this.question.multiSelect ? [...this.selected].sort((a, b) => a - b) : [this.selectedIndex]
+      if (indices.length === 0) {
+        this.error = 'Select at least one option, or press C for a custom answer.'
+        return
+      }
+      this.done({ selected: indices.map(index => options[index]?.label).filter((label): label is string => label !== undefined) })
+    } else if (data.toLowerCase() === 'c') {
+      this.mode = 'custom'
+      this.error = ''
+    } else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl('c'))) {
+      this.cancel()
+    }
+  }
+
+  private submitCustom(value: string): void {
+    const custom = value.trim()
+    if (custom === '') {
+      this.error = 'Enter an answer before submitting.'
+      return
+    }
+    this.done({ selected: [], custom })
+  }
+
+  render(width: number): string[] {
+    this.input.focused = this.focused
+    const innerWidth = Math.max(1, width - 4)
+    const title = displayText(this.question.header ?? 'Question')
+    const topLabel = ` ${title} `
+    const top = `╭${topLabel}${'─'.repeat(Math.max(0, width - visibleWidth(topLabel) - 2))}╮`
+    const lines: string[] = [this.palette.accent(top)]
+    const push = (line: string): void => {
+      const clipped = truncateToWidth(line, innerWidth, '')
+      lines.push(`${this.palette.accent('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${this.palette.accent('│')}`)
+    }
+    for (const line of wrapTextWithAnsi(this.palette.bold(displayText(this.question.question)), innerWidth)) push(line)
+    push('')
+    if (this.mode === 'custom') {
+      for (const line of this.input.render(innerWidth)) push(line)
+      push(this.palette.dim(this.options.length > 0 ? 'Enter submit • Esc options' : 'Enter submit • Esc cancel'))
+    } else {
+      const options = this.options
+      const start = Math.max(0, Math.min(
+        this.selectedIndex - Math.floor(this.maxVisible / 2),
+        options.length - this.maxVisible,
+      ))
+      const end = Math.min(options.length, start + this.maxVisible)
+      for (let index = start; index < end; index += 1) {
+        // `index < end <= options.length`; the options array is borrowed immutably for this dialog.
+        const option = options[index] as NonNullable<AskUserQuestionItem['options']>[number]
+        const cursor = index === this.selectedIndex ? this.palette.accent('›') : ' '
+        const mark = this.question.multiSelect
+          ? this.selected.has(index) ? this.palette.success('[x]') : '[ ]'
+          : index === this.selectedIndex ? this.palette.accent('●') : this.palette.dim('○')
+        const description = option.description
+          ? this.palette.muted(` — ${displayText(option.description)}`)
+          : ''
+        const line = `${cursor} ${mark} ${displayText(option.label)}${description}`
+        push(index === this.selectedIndex ? this.palette.selected(line) : line)
+      }
+      if (options.length > this.maxVisible) push(this.palette.dim(`${this.selectedIndex + 1}/${options.length}`))
+      push(this.palette.dim(this.question.multiSelect
+        ? '↑↓ navigate • Space toggle • Enter submit • C custom • Esc cancel'
+        : '↑↓ navigate • Enter select • C custom • Esc cancel'))
+    }
+    if (this.error) push(this.palette.error(this.error))
+    lines.push(this.palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`))
+    return lines
+  }
+}
+
+interface PendingQuestion {
+  request: AskUserQuestionRequest
+  index: number
+  answers: AskUserQuestionAnswerItem[]
+  resolve(answer: AskUserQuestionAnswer): void
+  reject(error: unknown): void
+  onAbort: () => void
+  overlay: OverlayHandle | undefined
+}
+
+/** Lifecycle handle for a mounted interactive terminal channel. */
+export interface TuiController {
+  /** Stop rendering, restore the terminal, and reject pending questions. */
+  dispose(): Promise<void>
+}
+
+function activeSurfaceSeqs(session: Session): Set<number> {
+  return new Set(session.surface.nodes)
+}
+
+function activeToolCallIds(session: Session, active: ReadonlySet<number>): Set<string> {
+  const ids = new Set<string>()
+  for (const event of session.events) {
+    if (event.type !== 'assistant/message' || !active.has(event.seq)) continue
+    for (const block of event.data.content) {
+      if (block.type === 'tool-call') ids.add(block.id)
+    }
+  }
+  return ids
+}
+
+/**
+ * Start the interactive pi-tui channel for an already-created target agent.
+ * @param ctx - agent, tools, session-event, and user-interaction context.
+ * @param config - target agent, banner, and TUI presentation config.
+ * @param runtime - terminal and process-exit boundary.
+ * @returns lifecycle controller used by the Cordis effect disposer.
+ */
+export function createTuiChat(
+  ctx: Context,
+  config: Config,
+  runtime: TuiRuntime,
+): TuiController {
+  const sessionId = SessionId(config.sessionId ?? 'main')
+  const agent = ctx.agents.get(sessionId)
+  if (agent === undefined) throw new Error(`ui-tui: session "${sessionId}" is not running`)
+  const resolved = resolveTuiConfig(config)
+  const palette = createPalette(resolved.color)
+  const mdTheme = markdownTheme(palette)
+  const ui = new TUI(runtime.terminal, resolved.showHardwareCursor)
+  const chat = new Container()
+  const todoContainer = new Container()
+  const statusContainer = new Container()
+  const editor = new Editor(ui, {
+    borderColor: palette.dim,
+    selectList: selectTheme(palette),
+  } satisfies EditorTheme, { paddingX: 1 })
+  const todo = new TodoComponent(palette)
+  let showReasoning = resolved.showReasoning
+  let toolsExpanded = false
+  let streaming: StreamingAssistantComponent | undefined
+  let statusLoader: Loader | undefined
+  let disposed = false
+  let shuttingDown: Promise<void> | undefined
+  const tokens = sessionTokens(agent.session)
+  const toolCards = new Map<string, ToolCardComponent>()
+  const allToolCards = new Set<ToolCardComponent>()
+  const liveErrors = new Set<string>()
+  const questionQueue: PendingQuestion[] = []
+  let activeQuestion: PendingQuestion | undefined
+
+  const welcome = config.welcome ?? 'ready.'
+  const header = new HeaderComponent(agent, welcome, palette)
+  const footer = new FooterComponent(agent, palette, () => toolsExpanded, () => showReasoning, () => tokens)
+  ui.addChild(header)
+  ui.addChild(chat)
+  ui.addChild(statusContainer)
+  todoContainer.addChild(todo)
+  ui.addChild(todoContainer)
+  ui.addChild(editor)
+  ui.addChild(footer)
+  ui.setFocus(editor)
+  runtime.terminal.setTitle(displayText(resolved.title))
+
+  const requestRender = (): void => {
+    footer.invalidate()
+    ui.requestRender()
+  }
+
+  const appendNotice = (message: string, kind: 'info' | 'warning' | 'error' = 'info'): void => {
+    const color = kind === 'error' ? palette.error : kind === 'warning' ? palette.warning : palette.muted
+    chat.addChild(new Spacer(1))
+    chat.addChild(new Text(color(displayText(message)), 1, 0))
+    requestRender()
+  }
+
+  const clearStatus = (): void => {
+    statusLoader?.stop()
+    statusLoader = undefined
+    statusContainer.clear()
+    runtime.terminal.setProgress(false)
+  }
+
+  const setStatus = (status: AgentStatus): void => {
+    clearStatus()
+    editor.borderColor = status === 'running' ? text => palette.accent(text) : text => palette.dim(text)
+    if (status === 'running') {
+      statusLoader = new Loader(ui, text => palette.accent(text), text => palette.muted(text), 'Working — Enter sends steering, Esc cancels')
+      statusContainer.addChild(statusLoader)
+      runtime.terminal.setProgress(true)
+    }
+    requestRender()
+  }
+
+  const parsedTool = (event: Extract<SessionEvent, { type: 'tool/call' }>): ToolCardComponent => {
+    const parsed = parseArguments(event.data.arguments)
+    const card = new ToolCardComponent(
+      event.data.name,
+      parsed,
+      ctx.tools.get(event.data.name, agent),
+      resolved.maxToolOutputLines,
+      palette,
+    )
+    card.setExpanded(toolsExpanded)
+    toolCards.set(event.data.callId, card)
+    allToolCards.add(card)
+    return card
+  }
+
+  const renderEvent = (event: SessionEvent, options: { addHistory: boolean; renderChunks: boolean }): void => {
+    switch (event.type) {
+      case 'user/message': {
+        const text = displayText(contentText(event.data.content).trim())
+        if (text) {
+          chat.addChild(new Spacer(1))
+          chat.addChild(new UserMessageComponent(text, palette, mdTheme))
+          if (options.addHistory) editor.addToHistory(text)
+        }
+        break
+      }
+      case 'steering/message': {
+        const text = displayText(contentText(event.data.content).trim())
+        if (text) {
+          chat.addChild(new Spacer(1))
+          chat.addChild(new UserMessageComponent(text, palette, mdTheme, 'Steering'))
+        }
+        break
+      }
+      case 'context/message': {
+        const text = displayText(contentText(event.data.content).trim())
+        if (text) {
+          const source = event.data.source.kind === 'plugin' ? event.data.source.plugin : event.data.source.kind
+          chat.addChild(new Spacer(1))
+          chat.addChild(new Text(palette.dim(`Context · ${displayText(source)}`), 1, 0))
+          chat.addChild(new Text(palette.muted(text), 1, 0))
+        }
+        break
+      }
+      case 'prompt/blocked':
+        appendNotice(`Prompt blocked: ${event.data.reason}`, 'warning')
+        break
+      case 'assistant/chunk':
+        if (options.renderChunks) {
+          if (streaming === undefined) {
+            streaming = new StreamingAssistantComponent(showReasoning, palette, mdTheme)
+            chat.addChild(streaming)
+          }
+          streaming.update(event.data.chunk)
+        }
+        break
+      case 'assistant/message': {
+        if (streaming !== undefined) {
+          const index = chat.children.indexOf(streaming)
+          if (index >= 0) chat.children.splice(index, 1)
+          streaming = undefined
+        }
+        const component = new AssistantMessageComponent(event.data.content, showReasoning, palette, mdTheme)
+        if (component.children.length > 0) chat.addChild(component)
+        break
+      }
+      case 'tool/call':
+        chat.addChild(new Spacer(1))
+        chat.addChild(parsedTool(event))
+        break
+      case 'tool/result': {
+        let card = toolCards.get(event.data.callId)
+        if (card === undefined) {
+          card = new ToolCardComponent('tool', { value: {}, valid: true }, undefined, resolved.maxToolOutputLines, palette)
+          chat.addChild(new Spacer(1))
+          chat.addChild(card)
+          allToolCards.add(card)
+        }
+        card.updateResult(event.data)
+        toolCards.delete(event.data.callId)
+        break
+      }
+      case 'todo/write':
+        todo.update(event.data.todos)
+        break
+      case 'turn/end':
+        if (event.data.reason.kind === 'error') {
+          const key = `${event.data.turn}:${event.data.reason.step}`
+          if (!liveErrors.delete(key)) appendNotice(event.data.reason.message, 'error')
+        } else if (event.data.reason.kind === 'aborted') {
+          appendNotice(event.data.reason.reason ?? 'Turn cancelled.', 'warning')
+        } else if (event.data.reason.kind === 'max-tokens') {
+          appendNotice('The model reached its output-token limit.', 'warning')
+        } else if (event.data.reason.kind === 'rejected') {
+          appendNotice(`Turn rejected: ${event.data.reason.reason}`, 'warning')
+        } else if (event.data.reason.kind === 'interrupted') {
+          appendNotice('The previous process ended during this turn.', 'warning')
+        }
+        break
+      default:
+        break
+    }
+  }
+
+  const rebuildTranscript = (populateHistory: boolean): void => {
+    chat.clear()
+    toolCards.clear()
+    allToolCards.clear()
+    streaming = undefined
+    const active = activeSurfaceSeqs(agent.session)
+    const activeCalls = activeToolCallIds(agent.session, active)
+    for (const event of agent.session.events) {
+      const isSurface = event.type === 'user/message'
+        || event.type === 'assistant/message'
+        || event.type === 'tool/result'
+        || event.type === 'context/message'
+        || event.type === 'steering/message'
+      if (isSurface && !active.has(event.seq)) continue
+      if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue
+      renderEvent(event, { addHistory: populateHistory, renderChunks: false })
+    }
+    requestRender()
+  }
+
+  const removeAbortListener = (pending: PendingQuestion): void => {
+    pending.request.signal?.removeEventListener('abort', pending.onAbort)
+  }
+
+  const rejectQuestion = (pending: PendingQuestion): void => {
+    pending.overlay?.hide()
+    pending.overlay = undefined
+    removeAbortListener(pending)
+    pending.reject(new UserInteractionError(
+      'ask_user_question was interrupted before the user answered',
+      'ASK_ABORTED',
+    ))
+  }
+
+  const startNextQuestion = (): void => {
+    if (activeQuestion !== undefined || disposed) return
+    const pending = questionQueue.shift()
+    if (pending === undefined) return
+    activeQuestion = pending
+    const show = (): void => {
+      const question = pending.request.questions[pending.index]
+      if (question === undefined) {
+        activeQuestion = undefined
+        removeAbortListener(pending)
+        pending.resolve({ answers: pending.answers })
+        startNextQuestion()
+        return
+      }
+      const dialog = new QuestionDialog(
+        question,
+        resolved.maxQuestionOptions,
+        palette,
+        (selection) => {
+          pending.overlay?.hide()
+          pending.overlay = undefined
+          pending.answers.push({ id: question.id, ...selection })
+          pending.index += 1
+          show()
+        },
+        () => {
+          activeQuestion = undefined
+          rejectQuestion(pending)
+          startNextQuestion()
+        },
+      )
+      pending.overlay = ui.showOverlay(dialog, {
+        width: resolved.questionDialogWidth,
+        maxHeight: resolved.questionDialogMaxHeight,
+        anchor: 'center',
+        margin: 1,
+      })
+      requestRender()
+    }
+    show()
+  }
+
+  const disposeUserInteraction = ctx.userInteraction.registerProvider({
+    ask(request) {
+      return new Promise<AskUserQuestionAnswer>((resolveAnswer, reject) => {
+        const pending: PendingQuestion = {
+          request,
+          index: 0,
+          answers: [],
+          resolve: resolveAnswer,
+          reject,
+          overlay: undefined,
+          onAbort: () => {
+            if (activeQuestion === pending) {
+              activeQuestion = undefined
+              rejectQuestion(pending)
+              startNextQuestion()
+              return
+            }
+            // A non-active pending ask remains in the queue until this listener settles it.
+            questionQueue.splice(questionQueue.indexOf(pending), 1)
+            rejectQuestion(pending)
+          },
+        }
+        request.signal?.addEventListener('abort', pending.onAbort, { once: true })
+        questionQueue.push(pending)
+        startNextQuestion()
+      })
+    },
+  })
+
+  const shutdown = (exitProcess: boolean): Promise<void> => {
+    shuttingDown ??= (async () => {
+      disposed = true
+      clearStatus()
+      if (activeQuestion !== undefined) {
+        const pending = activeQuestion
+        activeQuestion = undefined
+        rejectQuestion(pending)
+      }
+      for (const pending of questionQueue.splice(0)) rejectQuestion(pending)
+      disposeUserInteraction()
+      await runtime.terminal.drainInput(100, 20)
+      ui.stop()
+      if (exitProcess) runtime.exit(0)
+    })()
+    return shuttingDown
+  }
+
+  const requestExit = (): void => {
+    if (agent.status === 'running') {
+      agent.cancel('terminal exit requested')
+      appendNotice('Cancelling the active turn before exit…', 'warning')
+      void agent.whenIdle().then(() => shutdown(true))
+      return
+    }
+    void shutdown(true)
+  }
+
+  editor.setAutocompleteProvider(new CombinedAutocompleteProvider([
+    { name: 'help', description: 'Show keyboard shortcuts and commands' },
+    { name: 'clear', description: 'Clear the transcript view (session history is unchanged)' },
+    { name: 'cancel', description: 'Cancel the active turn' },
+    { name: 'reasoning', description: 'Toggle reasoning blocks' },
+    { name: 'tools', description: 'Expand or collapse all tool cards' },
+    { name: 'redraw', description: 'Invalidate components and redraw the terminal' },
+    { name: 'exit', description: 'Exit after the active turn reaches idle' },
+  ], agent.session.header.cwd ?? process.cwd()))
+
+  const toggleTools = (): void => {
+    toolsExpanded = !toolsExpanded
+    for (const card of allToolCards) card.setExpanded(toolsExpanded)
+    appendNotice(`Tool cards ${toolsExpanded ? 'expanded' : 'collapsed'}.`)
+  }
+
+  const toggleReasoning = (): void => {
+    showReasoning = !showReasoning
+    const activeStreaming = streaming
+    rebuildTranscript(false)
+    if (activeStreaming !== undefined) {
+      streaming = activeStreaming
+      streaming.setShowReasoning(showReasoning)
+      chat.addChild(activeStreaming)
+    }
+    appendNotice(`Reasoning blocks ${showReasoning ? 'shown' : 'hidden'}.`)
+  }
+
+  const showHelp = (): void => {
+    chat.addChild(new Spacer(1))
+    chat.addChild(new Text(palette.bold(palette.accent('Keyboard shortcuts')), 1, 0))
+    chat.addChild(new Text([
+      'Enter send • Shift/Alt+Enter newline • Up/Down prompt history',
+      'Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning',
+      'Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit',
+      '/help /clear /cancel /reasoning /tools /redraw /exit',
+    ].map(line => palette.muted(line)).join('\n'), 1, 0))
+    requestRender()
+  }
+
+  editor.onSubmit = (value: string) => {
+    const text = value.trim()
+    if (text === '') return
+    editor.addToHistory(text)
+    editor.setText('')
+    switch (text) {
+      case '/help':
+        showHelp()
+        return
+      case '/clear':
+        chat.clear()
+        requestRender()
+        return
+      case '/cancel':
+        if (agent.status === 'running') agent.cancel('cancelled from terminal')
+        else appendNotice('The agent is already idle.')
+        return
+      case '/reasoning':
+        toggleReasoning()
+        return
+      case '/tools':
+        toggleTools()
+        return
+      case '/redraw':
+        ui.invalidate()
+        ui.requestRender(true)
+        return
+      case '/exit':
+        requestExit()
+        return
+      default:
+        if (text.startsWith('/')) {
+          appendNotice(`Unknown command: ${text}`, 'warning')
+          return
+        }
+    }
+    if (agent.status === 'disposed') {
+      appendNotice(`Agent "${agent.id}" is disposed.`, 'error')
+    } else if (agent.status === 'running') {
+      agent.steer([{ type: 'text', text }])
+    } else {
+      agent.send([{ type: 'text', text }])
+    }
+  }
+
+  const removeInputListener = ui.addInputListener((data) => {
+    if (activeQuestion !== undefined) return undefined
+    if (matchesKey(data, Key.ctrl('o'))) {
+      toggleTools()
+      return { consume: true }
+    }
+    if (matchesKey(data, Key.ctrl('r'))) {
+      toggleReasoning()
+      return { consume: true }
+    }
+    if (matchesKey(data, Key.ctrl('l'))) {
+      ui.invalidate()
+      ui.requestRender(true)
+      return { consume: true }
+    }
+    if (matchesKey(data, Key.escape) && agent.status === 'running') {
+      agent.cancel('cancelled from terminal')
+      return { consume: true }
+    }
+    if (matchesKey(data, Key.ctrl('c'))) {
+      if (agent.status === 'running') {
+        agent.cancel('cancelled from terminal')
+      } else if (editor.getText() !== '') {
+        editor.setText('')
+      } else {
+        requestExit()
+      }
+      return { consume: true }
+    }
+    if (matchesKey(data, Key.ctrl('d'))) {
+      if (agent.status === 'running') appendNotice('Cancel the active turn before exiting.', 'warning')
+      else requestExit()
+      return { consume: true }
+    }
+    return undefined
+  })
+
+  const disposeSessionEvents = ctx.on('session/event', (session, event) => {
+    if (session !== agent.session) return
+    if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+      tokens.input += event.data.usage.inputTokens
+      tokens.output += event.data.usage.outputTokens
+    }
+    if ('surfaceOp' in event && typeof event.surfaceOp === 'object') {
+      rebuildTranscript(false)
+      return
+    }
+    renderEvent(event, { addHistory: false, renderChunks: true })
+    requestRender()
+  })
+  const disposeStatus = ctx.on('agent/status', (subject, status) => {
+    if (subject !== agent) return
+    setStatus(status)
+  })
+  const disposeError = ctx.on('agent/error', (subject, turn, step, error) => {
+    if (subject !== agent) return
+    liveErrors.add(`${turn}:${step}`)
+    appendNotice(error.message, 'error')
+  })
+  const disposeAgent = ctx.on('agent/disposed', (subject) => {
+    if (subject !== agent) return
+    clearStatus()
+    appendNotice(`Agent "${agent.id}" was disposed.`, 'warning')
+  })
+
+  const detachListeners = (): void => {
+    removeInputListener()
+    disposeSessionEvents()
+    disposeStatus()
+    disposeError()
+    disposeAgent()
+  }
+
+  rebuildTranscript(true)
+  setStatus(agent.status)
+  try {
+    ui.start()
+  } catch (error: unknown) {
+    disposed = true
+    detachListeners()
+    clearStatus()
+    disposeUserInteraction()
+    ui.stop()
+    throw error
+  }
+
+  return {
+    async dispose(): Promise<void> {
+      detachListeners()
+      await shutdown(false)
+    },
+  }
+}
+
+/**
+ * Open the pi-tui channel once its configured agent exists.
+ *
+ * @param ctx - Context supplying the agent registry, tools, and event stream.
+ * @param config - Target agent and presentation configuration.
+ * @param runtime - Terminal and process-exit boundary.
+ */
+export function mountTui(ctx: Context, config: Config, runtime: TuiRuntime): void {
+  const sessionId = SessionId(config.sessionId ?? 'main')
+  const matchesConfiguredIdentity = (agent: Agent): boolean =>
+    agent.id === sessionId && ctx.agents.roots().includes(agent)
+  let settled = false
+
+  const stopWaiting = (): void => {
+    disposeCreated()
+    disposeFailure()
+  }
+  const start = (agent: Agent): void => {
+    if (settled || !matchesConfiguredIdentity(agent)) return
+    settled = true
+    stopWaiting()
+    ctx.effect(() => {
+      const controller = createTuiChat(ctx, config, runtime)
+      return () => controller.dispose()
+    }, 'ui-tui')
+  }
+  const fail = (failedSessionId: SessionId, error: unknown): void => {
+    if (settled || failedSessionId !== sessionId) return
+    settled = true
+    stopWaiting()
+    runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${renderThrown(error)}\n`))
+    runtime.exit(1)
+  }
+
+  const disposeCreated = ctx.on('agent/created', start)
+  const disposeFailure = ctx.on('agent-loop/config-start-failed', fail)
+  const existing = ctx.agents.roots().find(agent => agent.id === sessionId)
+  if (existing !== undefined) start(existing)
+}
+
+/** Cordis entry point using the process terminal; explicit TUI composition requires a TTY pair. */
+/* v8 ignore start -- production process wiring; fake-terminal tests cover mountTui/createTuiChat,
+   and the coding-agent PTY smoke covers the real entry */
+export function apply(ctx: Context, config: Config): void {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('ui-tui: both stdin and stdout must be TTYs; use @deepseek-ai/dsh-stdio for pipes')
+  }
+  mountTui(ctx, config, {
+    terminal: new ProcessTerminal(),
+    exit: code => process.exit(code),
+  })
+}
+/* v8 ignore stop */
diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts
new file mode 100644
index 0000000000..9994833308
--- /dev/null
+++ b/packages/ui/tui/tests/harness.ts
@@ -0,0 +1,131 @@
+import { Context } from 'cordis'
+import type { Terminal } from '@earendil-works/pi-tui'
+import AgentRegistry, { 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, type Config } from '../src/index.ts'
+
+interface FakeAgent extends Agent {
+  status: AgentStatus
+  sent: ContentBlock[][]
+  steered: ContentBlock[][]
+  cancelled: string[]
+}
+
+export interface TuiHarnessOptions {
+  status?: AgentStatus
+  config?: Config
+  tools?: Record<string, ToolDefinition>
+  configureContext?: (ctx: Context) => Promise<void>
+  beforeMount?: (session: Session) => void
+  cwd?: string | null
+}
+
+export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
+  ctx: Context
+  session: Session
+  agent: FakeAgent
+  terminal: TerminalType
+  exit: Exit
+  controller: ReturnType<typeof createTuiChat>
+}
+
+/**
+ * Compose the production TUI around an in-memory session and controllable agent.
+ * @param terminal - Terminal boundary driven by the test.
+ * @param exit - Process-exit observer.
+ * @param options - Initial session, agent, tool, and TUI configuration.
+ * @returns The mounted TUI and every boundary the test may drive or inspect.
+ */
+export async function createTuiTestHarness<TerminalType extends Terminal, Exit extends (code: number) => void>(
+  terminal: TerminalType,
+  exit: Exit,
+  options: TuiHarnessOptions = {},
+): Promise<TuiHarness<TerminalType, Exit>> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  if (options.configureContext === undefined) {
+    const tools = options.tools ?? {}
+    ctx.provide('tools', {
+      get(name: string) {
+        return tools[name]
+      },
+    } as never)
+  } else {
+    await options.configureContext(ctx)
+  }
+  const sessionId = SessionId('main-session')
+  const session = ctx.sessions.create(
+    sessionId,
+    options.cwd === null ? undefined : { meta: { cwd: options.cwd ?? '/workspace' } },
+  )
+  options.beforeMount?.(session)
+  const sent: ContentBlock[][] = []
+  const steered: ContentBlock[][] = []
+  const cancelled: string[] = []
+  const agent: FakeAgent = {
+    id: sessionId,
+    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 controller = createTuiChat(ctx, Object.assign({
+    welcome: 'Coding agent ready.',
+    sessionId,
+    color: false,
+  }, options.config), { terminal, exit })
+  return { ctx, session, agent, terminal, exit, controller }
+}
+
+/** Dispose the mounted TUI before its owning Cordis context. */
+export async function disposeTuiTestHarness(
+  setup: Pick<TuiHarness<Terminal, (code: number) => void>, 'controller' | 'ctx'>,
+): Promise<void> {
+  await setup.controller.dispose()
+  await setup.ctx.fiber.dispose()
+}
+
+/** Append a production-shaped user message to the active session surface. */
+export function appendUser(session: Session, text: string): void {
+  session.append('user/message', {
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+/** Append a production-shaped assistant message to the active session surface. */
+export function appendAssistant(
+  session: Session,
+  content: ContentBlock[],
+  usage?: { inputTokens: number; outputTokens: number },
+): void {
+  session.append('assistant/message', {
+    turn: 1,
+    step: 0,
+    provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+    content,
+    ...usage === undefined ? {} : { usage },
+  }, { surfaceOp: 'append' })
+}
diff --git a/packages/ui/tui/tests/headless-terminal.ts b/packages/ui/tui/tests/headless-terminal.ts
new file mode 100644
index 0000000000..1155016ab7
--- /dev/null
+++ b/packages/ui/tui/tests/headless-terminal.ts
@@ -0,0 +1,318 @@
+import type { Terminal } from '@earendil-works/pi-tui'
+import { Terminal as XtermTerminal, type IBufferCell } from '@xterm/headless'
+
+const FRAME_END = '\x1b[?2026l'
+const FRAME_TIMEOUT_MS = 2_000
+
+const ANSI_COLORS = [
+  'black',
+  'red',
+  'green',
+  'yellow',
+  'blue',
+  'magenta',
+  'cyan',
+  'white',
+  'bright-black',
+  'bright-red',
+  'bright-green',
+  'bright-yellow',
+  'bright-blue',
+  'bright-magenta',
+  'bright-cyan',
+  'bright-white',
+] as const
+
+interface FrameWaiter {
+  target: number
+  resolve: () => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+interface RowSnapshot {
+  text: string
+  wrapped: boolean
+  styles: string[]
+}
+
+export interface TerminalSnapshotOptions {
+  /** Include the whole active buffer instead of only the visible viewport. */
+  includeScrollback?: boolean
+}
+
+function occurrenceCount(value: string, needle: string): number {
+  let count = 0
+  let offset = 0
+  while (true) {
+    const match = value.indexOf(needle, offset)
+    if (match < 0) return count
+    count += 1
+    offset = match + needle.length
+  }
+}
+
+function colorLabel(cell: IBufferCell, kind: 'fg' | 'bg'): string | undefined {
+  const isDefault = kind === 'fg' ? cell.isFgDefault() : cell.isBgDefault()
+  if (isDefault) return undefined
+  const isRgb = kind === 'fg' ? cell.isFgRGB() : cell.isBgRGB()
+  const value = kind === 'fg' ? cell.getFgColor() : cell.getBgColor()
+  if (isRgb) return `${kind}=#${value.toString(16).padStart(6, '0')}`
+  const name = ANSI_COLORS[value]
+  return `${kind}=${name ?? `ansi-${value}`}`
+}
+
+function styleLabel(cell: IBufferCell): string {
+  const labels = [
+    colorLabel(cell, 'fg'),
+    colorLabel(cell, 'bg'),
+    cell.isBold() !== 0 ? 'bold' : undefined,
+    cell.isDim() !== 0 ? 'dim' : undefined,
+    cell.isItalic() !== 0 ? 'italic' : undefined,
+    cell.isUnderline() !== 0 ? 'underline' : undefined,
+    cell.isBlink() !== 0 ? 'blink' : undefined,
+    cell.isInverse() !== 0 ? 'inverse' : undefined,
+    cell.isInvisible() !== 0 ? 'invisible' : undefined,
+    cell.isStrikethrough() !== 0 ? 'strike' : undefined,
+    cell.isOverline() !== 0 ? 'overline' : undefined,
+  ].filter((label): label is string => label !== undefined)
+  return labels.join(' ')
+}
+
+function snapshotRow(terminal: XtermTerminal, row: number): RowSnapshot {
+  const line = terminal.buffer.active.getLine(row)
+  if (line === undefined) return { text: '', wrapped: false, styles: [] }
+  const styles: string[] = []
+  let activeStyle = ''
+  let activeStart = 0
+  for (let column = 0; column <= terminal.cols; column++) {
+    const cell = column < terminal.cols ? line.getCell(column) : undefined
+    const style = cell === undefined ? '' : styleLabel(cell)
+    if (style === activeStyle) continue
+    if (activeStyle !== '') styles.push(`${activeStart}-${column - 1} ${activeStyle}`)
+    activeStyle = style
+    activeStart = column
+  }
+  return {
+    text: line.translateToString(true),
+    wrapped: line.isWrapped,
+    styles,
+  }
+}
+
+function renderRows(rows: readonly RowSnapshot[], firstRow: number): string[] {
+  const rendered: string[] = []
+  let blankStart: number | undefined
+  const flushBlanks = (end: number): void => {
+    if (blankStart === undefined) return
+    rendered.push(blankStart === end ? `${blankStart}| <blank>` : `${blankStart}-${end}| <blank>`)
+    blankStart = undefined
+  }
+  for (let index = 0; index < rows.length; index++) {
+    const absoluteRow = firstRow + index
+    const row = rows[index] as RowSnapshot
+    if (row.text === '' && row.styles.length === 0 && !row.wrapped) {
+      blankStart ??= absoluteRow
+      continue
+    }
+    flushBlanks(absoluteRow - 1)
+    rendered.push(`${absoluteRow}${row.wrapped ? '~' : ''}| ${JSON.stringify(row.text)}`)
+    for (const style of row.styles) rendered.push(`  style ${style}`)
+  }
+  flushBlanks(firstRow + rows.length - 1)
+  return rendered
+}
+
+/**
+ * Terminal emulator used by TUI snapshots. It consumes the same ANSI stream as
+ * a real terminal and exposes completed synchronized frames as an awaitable boundary.
+ */
+export class HeadlessTerminal implements Terminal {
+  readonly kittyProtocolActive = false
+  readonly drainInput = (): Promise<void> => Promise.resolve()
+  started = 0
+  stopped = 0
+  title = ''
+  progress = false
+  cursorVisible = true
+  frames = 0
+  private readonly emulator: XtermTerminal
+  private onInput: (data: string) => void = () => {}
+  private onResize: () => void = () => {}
+  private pendingWrite: Promise<void> = Promise.resolve()
+  private readonly frameWaiters = new Set<FrameWaiter>()
+
+  constructor(columns = 80, rows = 24) {
+    this.emulator = new XtermTerminal({
+      cols: columns,
+      rows,
+      scrollback: 1_000,
+      allowProposedApi: true,
+      drawBoldTextInBrightColors: false,
+      logLevel: 'off',
+    })
+  }
+
+  get columns(): number {
+    return this.emulator.cols
+  }
+
+  get rows(): number {
+    return this.emulator.rows
+  }
+
+  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 {
+    const completedFrames = occurrenceCount(data, FRAME_END)
+    this.pendingWrite = new Promise((resolve) => {
+      this.emulator.write(data, () => {
+        this.frames += completedFrames
+        for (const waiter of this.frameWaiters) {
+          if (this.frames < waiter.target) continue
+          clearTimeout(waiter.timer)
+          this.frameWaiters.delete(waiter)
+          waiter.resolve()
+        }
+        resolve()
+      })
+    })
+  }
+
+  moveBy(lines: number): void {
+    if (lines > 0) this.write(`\x1b[${lines}B`)
+    if (lines < 0) this.write(`\x1b[${-lines}A`)
+  }
+
+  hideCursor(): void {
+    this.cursorVisible = false
+    this.write('\x1b[?25l')
+  }
+
+  showCursor(): void {
+    this.cursorVisible = true
+    this.write('\x1b[?25h')
+  }
+
+  clearLine(): void {
+    this.write('\x1b[K')
+  }
+
+  clearFromCursor(): void {
+    this.write('\x1b[J')
+  }
+
+  clearScreen(): void {
+    this.write('\x1b[2J\x1b[H')
+  }
+
+  setTitle(title: string): void {
+    this.title = title
+    this.write(`\x1b]0;${title}\x07`)
+  }
+
+  setProgress(active: boolean): void {
+    this.progress = active
+  }
+
+  send(data: string): void {
+    this.onInput(data)
+  }
+
+  resize(columns: number, rows = this.rows): void {
+    this.emulator.resize(columns, rows)
+    this.onResize()
+  }
+
+  /** Wait until pi-tui completes a synchronized frame newer than `after`. */
+  async waitForFrame(after = this.frames): Promise<void> {
+    if (this.frames <= after) {
+      await new Promise<void>((resolve, reject) => {
+        const waiter: FrameWaiter = {
+          target: after + 1,
+          resolve,
+          reject,
+          timer: setTimeout(() => {
+            this.frameWaiters.delete(waiter)
+            reject(new Error(`TUI did not complete frame ${after + 1} within ${FRAME_TIMEOUT_MS}ms`))
+          }, FRAME_TIMEOUT_MS),
+        }
+        this.frameWaiters.add(waiter)
+      })
+    }
+    await this.flush()
+  }
+
+  /** Await every terminal write queued through the current task. */
+  async flush(): Promise<void> {
+    let pending: Promise<void>
+    do {
+      pending = this.pendingWrite
+      await pending
+    } while (pending !== this.pendingWrite)
+  }
+
+  /**
+   * Reject palette output that would become theme-specific in a user's terminal.
+   * @returns One location per RGB, extended-palette, or explicit-background cell.
+   */
+  themeViolations(): string[] {
+    const violations: string[] = []
+    const buffer = this.emulator.buffer.active
+    for (let row = 0; row < buffer.length; row++) {
+      const line = buffer.getLine(row)
+      if (line === undefined) continue
+      for (let column = 0; column < this.columns; column++) {
+        const cell = line.getCell(column)
+        if (cell === undefined) continue
+        const reasons = [
+          cell.isFgRGB() ? 'rgb-fg' : undefined,
+          cell.isBgRGB() ? 'rgb-bg' : undefined,
+          cell.isFgPalette() && cell.getFgColor() > 15 ? `extended-fg-${cell.getFgColor()}` : undefined,
+          cell.isBgPalette() && cell.getBgColor() > 15 ? `extended-bg-${cell.getBgColor()}` : undefined,
+          !cell.isBgDefault() ? 'explicit-bg' : undefined,
+        ].filter((reason): reason is string => reason !== undefined)
+        if (reasons.length > 0) violations.push(`${row}:${column} ${reasons.join(',')}`)
+      }
+    }
+    return violations
+  }
+
+  /** Serialize terminal cells and metadata into a stable, reviewable golden. */
+  async snapshot(options: TerminalSnapshotOptions = {}): Promise<string> {
+    await this.flush()
+    const buffer = this.emulator.buffer.active
+    const firstRow = options.includeScrollback === true ? 0 : buffer.viewportY
+    const rowCount = options.includeScrollback === true ? buffer.length : this.rows
+    const rows = Array.from({ length: rowCount }, (_, index) => snapshotRow(this.emulator, firstRow + index))
+    const cursorBufferRow = buffer.baseY + buffer.cursorY
+    const cursorViewportRow = cursorBufferRow - buffer.viewportY
+    return [
+      `terminal ${this.columns}x${this.rows} buffer=${buffer.type} length=${buffer.length} base=${buffer.baseY} viewport=${buffer.viewportY}`,
+      `lifecycle started=${this.started} stopped=${this.stopped} progress=${this.progress ? 'active' : 'inactive'}`,
+      `title ${JSON.stringify(this.title)}`,
+      `cursor ${this.cursorVisible ? 'visible' : 'hidden'} column=${buffer.cursorX} viewportRow=${cursorViewportRow} bufferRow=${cursorBufferRow}`,
+      options.includeScrollback === true ? 'buffer' : 'viewport',
+      ...renderRows(rows, firstRow),
+      '',
+    ].join('\n')
+  }
+
+  async dispose(): Promise<void> {
+    await this.flush()
+    for (const waiter of this.frameWaiters) {
+      clearTimeout(waiter.timer)
+      waiter.reject(new Error('terminal disposed before the requested frame completed'))
+    }
+    this.frameWaiters.clear()
+    this.emulator.dispose()
+  }
+}
diff --git a/packages/ui/tui/tests/plugin-shape.spec.ts b/packages/ui/tui/tests/plugin-shape.spec.ts
new file mode 100644
index 0000000000..d1e4b92f3d
--- /dev/null
+++ 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')
+  })
+})
diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.golden.txt b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.golden.txt
new file mode 100644
index 0000000000..dd563c0614
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.golden.txt
@@ -0,0 +1,107 @@
+terminal 100x40 buffer=normal length=41 base=1 viewport=1
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=37 bufferRow=38
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                            │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=green
+7| "▌ ✓ pnpm run test:coverage                                                                          "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-25 bold
+8| "▌ Run the coverage gate                                                                             "
+  style 0-0 fg=green
+  style 2-22 fg=bright-black
+9| "▌ /workspace/project                                                                                "
+  style 0-0 fg=green
+  style 2-19 dim
+10| "▌ packages/ui/tui 100%                                                                              "
+  style 0-0 fg=green
+11| "▌ … 4 more lines (Ctrl+O to expand)                                                                 "
+  style 0-0 fg=green
+  style 2-34 dim
+12| "▌ "
+  style 0-0 fg=green
+13| <blank>
+14| "▌ "
+  style 0-0 fg=green
+15| "▌ ✓ Edit renderer                                                                                   "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-16 bold
+16| "▌ src/view.ts                                                                                       "
+  style 0-0 fg=green
+  style 2-12 bold
+17| "▌ - old line                                                                                        "
+  style 0-0 fg=green
+  style 2-11 fg=red
+18| "▌ - keep                                                                                            "
+  style 0-0 fg=green
+  style 2-7 fg=red
+19| "▌ … 5 more lines (Ctrl+O to expand)                                                                 "
+  style 0-0 fg=green
+  style 2-34 dim
+20| "▌ "
+  style 0-0 fg=green
+21| <blank>
+22| "▌ "
+  style 0-0 fg=green
+23| "▌ ✓ Delegate renderer audit                                                                         "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-26 bold
+24| "▌ The renderer has explicit lifecycle ownership.                                                    "
+  style 0-0 fg=green
+25| "▌ "
+  style 0-0 fg=green
+26| <blank>
+27| "▌ "
+  style 0-0 fg=green
+28| "▌ ✓ Read output from background task subagent-7                                                     "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-46 bold
+29| "▌ audit complete                                                                                    "
+  style 0-0 fg=green
+30| "▌ [status: completed]                                                                               "
+  style 0-0 fg=green
+31| "▌ "
+  style 0-0 fg=green
+32| <blank>
+33| "▌ "
+  style 0-0 fg=green
+34| "▌ ✓ Load skill dsh-code-review                                                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-29 bold
+35| "▌ Loaded review instructions.                                                                       "
+  style 0-0 fg=green
+36| "▌ "
+  style 0-0 fg=green
+37| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+38| "                                                                                                    "
+  style 1-1 inverse
+39| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+40| "/workspace/project  ↑0 ↓0                                          idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 67-99 dim
diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-expanded.golden.txt b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.golden.txt
new file mode 100644
index 0000000000..147d7fcdb1
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.golden.txt
@@ -0,0 +1,127 @@
+terminal 100x40 buffer=normal length=50 base=10 viewport=10
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=37 bufferRow=47
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                            │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=green
+7| "▌ ✓ pnpm run test:coverage                                                                          "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-25 bold
+8| "▌ Run the coverage gate                                                                             "
+  style 0-0 fg=green
+  style 2-22 fg=bright-black
+9| "▌ /workspace/project                                                                                "
+  style 0-0 fg=green
+  style 2-19 dim
+10| "▌ packages/ui/tui 100%                                                                              "
+  style 0-0 fg=green
+11| "▌ 4016 tests passed                                                                                 "
+  style 0-0 fg=green
+12| "▌ 1 test skipped                                                                                    "
+  style 0-0 fg=green
+13| "▌ coverage complete                                                                                 "
+  style 0-0 fg=green
+14| "▌ [exit 0]                                                                                          "
+  style 0-0 fg=green
+  style 2-9 dim
+15| "▌ "
+  style 0-0 fg=green
+16| <blank>
+17| "▌ "
+  style 0-0 fg=green
+18| "▌ ✓ Edit renderer                                                                                   "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-16 bold
+19| "▌ src/view.ts                                                                                       "
+  style 0-0 fg=green
+  style 2-12 bold
+20| "▌ - old line                                                                                        "
+  style 0-0 fg=green
+  style 2-11 fg=red
+21| "▌ - keep                                                                                            "
+  style 0-0 fg=green
+  style 2-7 fg=red
+22| "▌ + new line                                                                                        "
+  style 0-0 fg=green
+  style 2-11 fg=green
+23| "▌ + keep                                                                                            "
+  style 0-0 fg=green
+  style 2-7 fg=green
+24| "▌                                                                                                   "
+  style 0-0 fg=green
+25| "▌ tests/view.spec.ts                                                                                "
+  style 0-0 fg=green
+  style 2-19 bold
+26| "▌ + expect(screen).toMatchSnapshot()                                                                "
+  style 0-0 fg=green
+  style 2-35 fg=green
+27| "▌ "
+  style 0-0 fg=green
+28| <blank>
+29| "▌ "
+  style 0-0 fg=green
+30| "▌ ✓ Delegate renderer audit                                                                         "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-26 bold
+31| "▌ The renderer has explicit lifecycle ownership.                                                    "
+  style 0-0 fg=green
+32| "▌ "
+  style 0-0 fg=green
+33| <blank>
+34| "▌ "
+  style 0-0 fg=green
+35| "▌ ✓ Read output from background task subagent-7                                                     "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-46 bold
+36| "▌ audit complete                                                                                    "
+  style 0-0 fg=green
+37| "▌ [status: completed]                                                                               "
+  style 0-0 fg=green
+38| "▌ "
+  style 0-0 fg=green
+39| <blank>
+40| "▌ "
+  style 0-0 fg=green
+41| "▌ ✓ Load skill dsh-code-review                                                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-29 bold
+42| "▌ Loaded review instructions.                                                                       "
+  style 0-0 fg=green
+43| "▌ "
+  style 0-0 fg=green
+44| <blank>
+45| " Tool cards expanded.                                                                               "
+  style 1-20 fg=bright-black
+46| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+47| "                                                                                                    "
+  style 1-1 inverse
+48| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+49| "/workspace/project  ↑0 ↓0                                         idle  reasoning:on  tools:expanded"
+  style 0-24 dim
+  style 66-99 dim
diff --git a/packages/ui/tui/tests/snapshots/code-mode-pending.golden.txt b/packages/ui/tui/tests/snapshots/code-mode-pending.golden.txt
new file mode 100644
index 0000000000..30deac56c6
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/code-mode-pending.golden.txt
@@ -0,0 +1,52 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=15 bufferRow=15
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-95 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 95-95 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 95-95 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                           │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 95-95 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-95 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=yellow
+7| "▌ ◌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                "
+  style 0-0 fg=yellow
+  style 2-2 fg=yellow bold
+  style 3-95 bold
+8| "▌ const second = await tools.bas                                                                "
+  style 0-0 fg=yellow
+  style 2-31 bold
+9| "▌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                  "
+  style 0-0 fg=yellow
+10| "▌ const second = await tools.bash({ command: 'echo CODE_TWO' })                                 "
+  style 0-0 fg=yellow
+11| "▌ console.log(first, second)                                                                    "
+  style 0-0 fg=yellow
+12| "▌ return `${first}+${second}`                                                                   "
+  style 0-0 fg=yellow
+13| "▌ "
+  style 0-0 fg=yellow
+14| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+15| "                                                                                                "
+  style 1-1 inverse
+16| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+17| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 63-95 dim
+18-35| <blank>
diff --git a/packages/ui/tui/tests/snapshots/conversation-streaming.golden.txt b/packages/ui/tui/tests/snapshots/conversation-streaming.golden.txt
new file mode 100644
index 0000000000..4b6ccdee48
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/conversation-streaming.golden.txt
@@ -0,0 +1,52 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=17 bufferRow=17
+viewport
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-95 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 95-95 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 95-95 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                           │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 95-95 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-95 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                           "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Show the live update.                                                                         "
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| " Reasoning                                                                                      "
+  style 1-9 fg=bright-black italic
+12| " Inspecting width and styles.                                                                   "
+  style 1-28 fg=bright-black italic
+13| <blank>
+14| " Assistant                                                                                      "
+  style 1-9 fg=bright-magenta bold
+15| " Streaming visible state…                                                                       "
+  style 11-23 bold
+16| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+17| "                                                                                                "
+  style 1-1 inverse
+18| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+19| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 63-95 dim
+20-35| <blank>
diff --git a/packages/ui/tui/tests/snapshots/cordis-tools-pending.golden.txt b/packages/ui/tui/tests/snapshots/cordis-tools-pending.golden.txt
new file mode 100644
index 0000000000..81d59edfec
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/cordis-tools-pending.golden.txt
@@ -0,0 +1,59 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=18 bufferRow=18
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-95 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 95-95 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 95-95 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                           │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 95-95 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-95 fg=bright-blue
+5| <blank>
+6| "▌ ◌ Inspect cordis runtime: tools                                                               "
+  style 0-0 fg=yellow
+  style 2-2 fg=yellow bold
+  style 3-32 bold
+7| <blank>
+8| "▌ "
+  style 0-0 fg=yellow
+9| "▌ ◌ Mount plugin into live cordis runtime                                                       "
+  style 0-0 fg=yellow
+  style 2-2 fg=yellow bold
+  style 3-40 bold
+10| "▌ {                                                                                             "
+  style 0-0 fg=yellow
+11| "▌   \"code\": \"return { name: 'snapshot-marker', apply(ctx) { ctx.provide('snapshotMarker', {     "
+  style 0-0 fg=yellow
+12| "▌ ready: true }) } }\"                                                                           "
+  style 0-0 fg=yellow
+13| "▌ }                                                                                             "
+  style 0-0 fg=yellow
+14| "▌ "
+  style 0-0 fg=yellow
+15| <blank>
+16| "▌ ◌ Unmount dyn-1                                                                               "
+  style 0-0 fg=yellow
+  style 2-2 fg=yellow bold
+  style 3-16 bold
+17| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+18| "                                                                                                "
+  style 1-1 inverse
+19| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+20| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 63-95 dim
+21-35| <blank>
diff --git a/packages/ui/tui/tests/snapshots/disposed-terminal.golden.txt b/packages/ui/tui/tests/snapshots/disposed-terminal.golden.txt
new file mode 100644
index 0000000000..05809dea0c
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/disposed-terminal.golden.txt
@@ -0,0 +1,52 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=1 progress=inactive
+title "DSH snapshot"
+cursor visible column=0 viewportRow=22 bufferRow=22
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-91 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 91-91 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                    │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 91-91 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                       │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 91-91 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-91 fg=bright-blue
+5| <blank>
+6| " Keyboard shortcuts                                                                         "
+  style 1-18 fg=bright-blue bold
+7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
+  style 1-61 fg=bright-black
+8| " Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning                "
+  style 1-75 fg=bright-black
+9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
+  style 1-73 fg=bright-black
+10| " /help /clear /cancel /reasoning /tools /redraw /exit                                       "
+  style 1-52 fg=bright-black
+11| <blank>
+12| " Unknown command: /unknown-advanced-command                                                 "
+  style 1-42 fg=yellow
+13| <blank>
+14| " provider stream failed after partial output                                                "
+  style 1-43 fg=red
+15| <blank>
+16| " The previous process ended during this turn.                                               "
+  style 1-44 fg=yellow
+17| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+18| "                                                                                            "
+  style 1-1 inverse
+19| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+20| "/workspace/project  ↑0 ↓0                                  idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 59-91 dim
+21-31| <blank>
diff --git a/packages/ui/tui/tests/snapshots/dynamic-workflow-pending.golden.txt b/packages/ui/tui/tests/snapshots/dynamic-workflow-pending.golden.txt
new file mode 100644
index 0000000000..02395a1ff0
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/dynamic-workflow-pending.golden.txt
@@ -0,0 +1,55 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=17 bufferRow=17
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-95 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 95-95 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 95-95 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                           │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 95-95 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-95 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=yellow
+7| "▌ ◌ workflow: tui-matrix                                                                        "
+  style 0-0 fg=yellow
+  style 2-2 fg=yellow bold
+  style 3-23 bold
+8| "▌ phase('Inspect')                                                                              "
+  style 0-0 fg=yellow
+9| "▌ const reports = await parallel([                                                              "
+  style 0-0 fg=yellow
+10| "▌   () => agent('Audit layout', { label: 'layout', phase: 'Inspect' }),                         "
+  style 0-0 fg=yellow
+11| "▌   () => agent('Audit lifecycle', { label: 'lifecycle', phase: 'Inspect' }),                   "
+  style 0-0 fg=yellow
+12| "▌ ])                                                                                            "
+  style 0-0 fg=yellow
+13| "▌ phase('Verify')                                                                               "
+  style 0-0 fg=yellow
+14| "▌ return { reports, verdict: 'covered' }                                                        "
+  style 0-0 fg=yellow
+15| "▌ "
+  style 0-0 fg=yellow
+16| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+17| "                                                                                                "
+  style 1-1 inverse
+18| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+19| "/workspace/project  ↑0 ↓0                                      idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 63-95 dim
+20-35| <blank>
diff --git a/packages/ui/tui/tests/snapshots/errors-and-help.golden.txt b/packages/ui/tui/tests/snapshots/errors-and-help.golden.txt
new file mode 100644
index 0000000000..fccfca604b
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/errors-and-help.golden.txt
@@ -0,0 +1,52 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=18 bufferRow=18
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-91 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                         │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 91-91 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                    │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 91-91 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                       │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 91-91 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-91 fg=bright-blue
+5| <blank>
+6| " Keyboard shortcuts                                                                         "
+  style 1-18 fg=bright-blue bold
+7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
+  style 1-61 fg=bright-black
+8| " Esc cancel active turn • Ctrl+O expand tool cards • Ctrl+R toggle reasoning                "
+  style 1-75 fg=bright-black
+9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
+  style 1-73 fg=bright-black
+10| " /help /clear /cancel /reasoning /tools /redraw /exit                                       "
+  style 1-52 fg=bright-black
+11| <blank>
+12| " Unknown command: /unknown-advanced-command                                                 "
+  style 1-42 fg=yellow
+13| <blank>
+14| " provider stream failed after partial output                                                "
+  style 1-43 fg=red
+15| <blank>
+16| " The previous process ended during this turn.                                               "
+  style 1-44 fg=yellow
+17| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+18| "                                                                                            "
+  style 1-1 inverse
+19| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+20| "/workspace/project  ↑0 ↓0                                  idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 59-91 dim
+21-31| <blank>
diff --git a/packages/ui/tui/tests/snapshots/question-dialog-validation.golden.txt b/packages/ui/tui/tests/snapshots/question-dialog-validation.golden.txt
new file mode 100644
index 0000000000..a2dc6676e2
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/question-dialog-validation.golden.txt
@@ -0,0 +1,69 @@
+terminal 56x20 buffer=normal length=20 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=56 viewportRow=13 bufferRow=13
+viewport
+0| "╭──────────────────────────────────────────────────────╮"
+  style 0-55 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                     │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 55-55 fg=bright-blue
+2| "│ Snapshot agent ready.                                │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 55-55 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                   │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 55-55 fg=bright-blue
+4| "╰───╭ Coverage ────────────────────────────────────╮───╯"
+  style 0-55 fg=bright-blue
+5| "────│ Which advanced TUI states belong in the      │────"
+  style 0-3 dim
+  style 4-4 fg=bright-blue
+  style 6-50 bold
+  style 51-51 fg=bright-blue bold
+  style 52-55 dim
+6| "    │ required matrix?                             │    "
+  style 1-1 inverse
+  style 4-4 fg=bright-blue
+  style 6-21 bold
+  style 51-51 fg=bright-blue
+7| "────│                                              │────"
+  style 0-3 dim
+  style 4-4 fg=bright-blue
+  style 51-51 fg=bright-blue
+  style 52-55 dim
+8| "/wor│ › [ ] Code Mode — run_code programs and capt │:com"
+  style 0-3 dim
+  style 4-4 fg=bright-blue
+  style 6-6 fg=bright-blue inverse
+  style 7-20 inverse
+  style 21-49 fg=bright-black inverse
+  style 51-51 fg=bright-blue
+  style 52-55 dim
+9| "    │   [ ] Workflows — phases and parallel agents │    "
+  style 4-4 fg=bright-blue
+  style 21-49 fg=bright-black
+  style 51-51 fg=bright-blue
+10| "    │   [ ] Cordis tools — inspect, mount, and unm │    "
+  style 4-4 fg=bright-blue
+  style 24-49 fg=bright-black
+  style 51-51 fg=bright-blue
+11| "    │ 1/4                                          │    "
+  style 4-4 fg=bright-blue
+  style 6-8 dim
+  style 51-51 fg=bright-blue
+12| "    │ ↑↓ navigate • Space toggle • Enter submit •  │    "
+  style 4-4 fg=bright-blue
+  style 6-49 dim
+  style 51-51 fg=bright-blue
+13| "    │ Select at least one option, or press C for a │    "
+  style 4-4 fg=bright-blue
+  style 6-49 fg=red
+  style 51-51 fg=bright-blue
+14| "    ╰──────────────────────────────────────────────╯    "
+  style 4-51 fg=bright-blue
+15-19| <blank>
diff --git a/packages/ui/tui/tests/snapshots/question-dialog.golden.txt b/packages/ui/tui/tests/snapshots/question-dialog.golden.txt
new file mode 100644
index 0000000000..95dc4f2496
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/question-dialog.golden.txt
@@ -0,0 +1,67 @@
+terminal 56x20 buffer=normal length=20 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=0 viewportRow=19 bufferRow=19
+viewport
+0| "╭──────────────────────────────────────────────────────╮"
+  style 0-55 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                     │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 55-55 fg=bright-blue
+2| "│ Snapshot agent ready.                                │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 55-55 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                   │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 55-55 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────╯"
+  style 0-55 fg=bright-blue
+5| "────╭ Coverage ────────────────────────────────────╮────"
+  style 0-3 dim
+  style 4-51 fg=bright-blue
+  style 52-55 dim
+6| "    │ Which advanced TUI states belong in the      │    "
+  style 1-1 inverse
+  style 4-4 fg=bright-blue
+  style 6-50 bold
+  style 51-51 fg=bright-blue bold
+7| "────│ required matrix?                             │────"
+  style 0-3 dim
+  style 4-4 fg=bright-blue
+  style 6-21 bold
+  style 51-51 fg=bright-blue
+  style 52-55 dim
+8| "/wor│                                              │:com"
+  style 0-3 dim
+  style 4-4 fg=bright-blue
+  style 51-51 fg=bright-blue
+  style 52-55 dim
+9| "    │ › [ ] Code Mode — run_code programs and capt │    "
+  style 4-4 fg=bright-blue
+  style 6-6 fg=bright-blue inverse
+  style 7-20 inverse
+  style 21-49 fg=bright-black inverse
+  style 51-51 fg=bright-blue
+10| "    │   [ ] Workflows — phases and parallel agents │    "
+  style 4-4 fg=bright-blue
+  style 21-49 fg=bright-black
+  style 51-51 fg=bright-blue
+11| "    │   [ ] Cordis tools — inspect, mount, and unm │    "
+  style 4-4 fg=bright-blue
+  style 24-49 fg=bright-black
+  style 51-51 fg=bright-blue
+12| "    │ 1/4                                          │    "
+  style 4-4 fg=bright-blue
+  style 6-8 dim
+  style 51-51 fg=bright-blue
+13| "    │ ↑↓ navigate • Space toggle • Enter submit •  │    "
+  style 4-4 fg=bright-blue
+  style 6-49 dim
+  style 51-51 fg=bright-blue
+14| "    ╰──────────────────────────────────────────────╯    "
+  style 4-51 fg=bright-blue
+15-19| <blank>
diff --git a/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.golden.txt b/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.golden.txt
new file mode 100644
index 0000000000..7c63f3491e
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.golden.txt
@@ -0,0 +1,41 @@
+terminal 44x18 buffer=normal length=18 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=11 bufferRow=11
+buffer
+0| "╭──────────────────────────────────────────╮"
+  style 0-43 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                         │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 43-43 fg=bright-blue
+2| "│ Snapshot agent ready.                    │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 43-43 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session       │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 43-43 fg=bright-blue
+4| "╰──────────────────────────────────────────╯"
+  style 0-43 fg=bright-blue
+5| <blank>
+6| " Context · compact                          "
+  style 1-17 dim
+7| " Compacted summary: the prior command       "
+  style 1-43 fg=bright-black
+8| " completed and its details were retired     "
+  style 1-43 fg=bright-black
+9| " from the active surface.                   "
+  style 1-24 fg=bright-black
+10| "────────────────────────────────────────────"
+  style 0-43 dim
+11| "                                            "
+  style 1-1 inverse
+12| "────────────────────────────────────────────"
+  style 0-43 dim
+13| "/workspace/project  ↑0 ↓0  idle  reasoning:o"
+  style 0-24 dim
+  style 27-43 dim
+14-17| <blank>
diff --git a/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.golden.txt b/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.golden.txt
new file mode 100644
index 0000000000..c5448befc8
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.golden.txt
@@ -0,0 +1,37 @@
+terminal 104x30 buffer=normal length=30 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=9 bufferRow=9
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-103 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                     │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 103-103 fg=bright-blue
+2| "│ Snapshot agent ready.                                                                                │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 103-103 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                                   │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 103-103 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-103 fg=bright-blue
+5| <blank>
+6| " Context · compact                                                                                      "
+  style 1-17 dim
+7| " Compacted summary: the prior command completed and its details were retired from the active surface.   "
+  style 1-100 fg=bright-black
+8| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-103 dim
+9| "                                                                                                        "
+  style 1-1 inverse
+10| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-103 dim
+11| "/workspace/project  ↑0 ↓0                                              idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 71-103 dim
+12-29| <blank>
diff --git a/packages/ui/tui/tests/snapshots/surface-before-compaction.golden.txt b/packages/ui/tui/tests/snapshots/surface-before-compaction.golden.txt
new file mode 100644
index 0000000000..5c2bbacb4e
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/surface-before-compaction.golden.txt
@@ -0,0 +1,67 @@
+terminal 80x24 buffer=normal length=25 base=1 viewport=1
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=21 bufferRow=22
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────╮"
+  style 0-79 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                             │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 79-79 fg=bright-blue
+2| "│ Snapshot agent ready.                                                        │"
+  style 0-0 fg=bright-blue
+  style 2-22 fg=bright-black
+  style 79-79 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                           │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 79-79 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────╯"
+  style 0-79 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                           "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Old prompt with a long line that exercises wrapping before compaction.        "
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| "▌ "
+  style 0-0 fg=green
+12| "▌ ✓ pnpm run test:coverage                                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-25 bold
+13| "▌ Run the coverage gate                                                         "
+  style 0-0 fg=green
+  style 2-22 fg=bright-black
+14| "▌ /workspace/project                                                            "
+  style 0-0 fg=green
+  style 2-19 dim
+15| "▌ packages/ui/tui 100%                                                          "
+  style 0-0 fg=green
+16| "▌ 4016 tests passed                                                             "
+  style 0-0 fg=green
+17| "▌ 1 test skipped                                                                "
+  style 0-0 fg=green
+18| "▌ coverage complete                                                             "
+  style 0-0 fg=green
+19| "▌ [exit 0]                                                                      "
+  style 0-0 fg=green
+  style 2-9 dim
+20| "▌ "
+  style 0-0 fg=green
+21| "────────────────────────────────────────────────────────────────────────────────"
+  style 0-79 dim
+22| "                                                                                "
+  style 1-1 inverse
+23| "────────────────────────────────────────────────────────────────────────────────"
+  style 0-79 dim
+24| "/workspace/project  ↑0 ↓0                      idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 47-79 dim
diff --git a/packages/ui/tui/tests/snapshots/untrusted-controls.golden.txt b/packages/ui/tui/tests/snapshots/untrusted-controls.golden.txt
new file mode 100644
index 0000000000..1d82ec3c45
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/untrusted-controls.golden.txt
@@ -0,0 +1,106 @@
+terminal 100x34 buffer=normal length=40 base=6 viewport=6
+lifecycle started=1 stopped=0 progress=inactive
+title "Unsafe terminal title \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m"
+cursor hidden column=100 viewportRow=33 bufferRow=39
+buffer
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-99 fg=bright-blue
+1| "│ DEEPSEEK HARNESS                                                                                 │"
+  style 0-0 fg=bright-blue
+  style 2-9 fg=bright-blue bold
+  style 11-17 bold
+  style 99-99 fg=bright-blue
+2| "│ Unsafe welcome \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                     │"
+  style 0-0 fg=bright-blue
+  style 2-61 fg=bright-black
+  style 99-99 fg=bright-blue
+3| "│ deepseek-v4-flash  •  main-session                                                               │"
+  style 0-0 fg=bright-blue
+  style 2-35 dim
+  style 99-99 fg=bright-blue
+4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-99 fg=bright-blue
+5| <blank>
+6| "▌ "
+  style 0-0 fg=bright-blue
+7| "▌ You                                                                                               "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+8| "▌ Unsafe user \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                         "
+  style 0-0 fg=bright-blue
+9| "▌ "
+  style 0-0 fg=bright-blue
+10| <blank>
+11| " Reasoning                                                                                          "
+  style 1-9 fg=bright-black italic
+12| " Unsafe reasoning \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                     "
+  style 1-62 fg=bright-black italic
+13| <blank>
+14| " Assistant                                                                                          "
+  style 1-9 fg=bright-magenta bold
+15| " Unsafe assistant \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                     "
+16| <blank>
+17| "▌ "
+  style 0-0 fg=green
+18| "▌ ✓ Unsafe title \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                      "
+  style 0-0 fg=green
+  style 2-2 fg=green bold
+  style 3-61 bold
+19| "▌ Unsafe description \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                  "
+  style 0-0 fg=green
+  style 2-65 fg=bright-black
+20| "▌ /unsafe/\\x1b╭ Unsafe header \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m ─────────╮              "
+  style 0-0 fg=green
+  style 2-13 dim
+  style 14-85 fg=bright-blue
+21| "▌ Unsafe outpu│ Unsafe question \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m        │              "
+  style 0-0 fg=green
+  style 14-14 fg=bright-blue
+  style 16-76 bold
+  style 85-85 fg=bright-blue
+22| "▌ [signal SIG\\│                                                                      │              "
+  style 0-0 fg=green
+  style 2-13 fg=red
+  style 14-14 fg=bright-blue
+  style 85-85 fg=bright-blue
+23| "▌             │ › ● Unsafe option \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m — Un │              "
+  style 0-0 fg=green
+  style 14-14 fg=bright-blue
+  style 16-16 fg=bright-blue inverse
+  style 17-17 inverse
+  style 18-18 fg=bright-blue inverse
+  style 19-78 inverse
+  style 79-83 fg=bright-black inverse
+  style 85-85 fg=bright-blue
+24| "              │ ↑↓ navigate • Enter select • C custom • Esc cancel                   │              "
+  style 14-14 fg=bright-blue
+  style 16-65 dim
+  style 85-85 fg=bright-blue
+25| " Context · uns╰──────────────────────────────────────────────────────────────────────╯              "
+  style 1-13 dim
+  style 14-85 fg=bright-blue
+26| " Unsafe context \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                       "
+  style 1-60 fg=bright-black
+27| <blank>
+28| " Prompt blocked: Unsafe policy \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                        "
+  style 1-75 fg=yellow
+29| <blank>
+30| " Unsafe turn error \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                    "
+  style 1-63 fg=red
+31| <blank>
+32| " Unsafe live error \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m                                    "
+  style 1-63 fg=red
+33| <blank>
+34| "Plan"
+  style 0-3 fg=bright-blue bold
+35| "  ● Unsafe todo \\x1b]2;snapshot-controlled\\x07\\x09\\x7f\\x9b31m"
+  style 2-2 fg=yellow
+36| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+37| "                                                                                                    "
+  style 1-1 inverse
+38| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+39| "/workspace/project  ↑0 ↓0                                          idle  reasoning:on  tools:compact"
+  style 0-24 dim
+  style 67-99 dim
diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts
new file mode 100644
index 0000000000..e0016184fd
--- /dev/null
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -0,0 +1,499 @@
+import { mkdir, readdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import type { Context } from 'cordis'
+import { CallId, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { Session } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { type ToolDefinition, type ToolResultView } from '@deepseek-ai/dsh-tools'
+import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
+import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import {
+  appendAssistant,
+  appendUser,
+  createTuiTestHarness,
+  disposeTuiTestHarness,
+  type TuiHarness,
+  type TuiHarnessOptions,
+} from './harness.ts'
+import { HeadlessTerminal, type TerminalSnapshotOptions } from './headless-terminal.ts'
+
+const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
+const REFRESHING = process.env.DSH_SNAPSHOT === 'refresh'
+
+const CHECKPOINTS = [
+  'conversation-streaming',
+  'code-mode-pending',
+  'dynamic-workflow-pending',
+  'cordis-tools-pending',
+  'advanced-cards-collapsed',
+  'advanced-cards-expanded',
+  'untrusted-controls',
+  'question-dialog',
+  'question-dialog-validation',
+  'surface-before-compaction',
+  'surface-after-compaction-narrow',
+  'surface-after-compaction-wide',
+  'errors-and-help',
+  'disposed-terminal',
+] as const
+
+type Checkpoint = typeof CHECKPOINTS[number]
+type SnapshotHarness = TuiHarness<HeadlessTerminal, (code: number) => void>
+
+const observedCheckpoints = new Set<Checkpoint>()
+
+async function checkpoint(
+  name: Checkpoint,
+  terminal: HeadlessTerminal,
+  options: TerminalSnapshotOptions = {},
+): Promise<void> {
+  observedCheckpoints.add(name)
+  expect(terminal.themeViolations(), `${name} must remain theme-agnostic`).toEqual([])
+  const snapshot = await terminal.snapshot(options)
+  const path = join(SNAPSHOTS_DIR, `${name}.golden.txt`)
+  if (REFRESHING) {
+    await mkdir(SNAPSHOTS_DIR, { recursive: true })
+    await writeFile(path, snapshot)
+  }
+  await expect(snapshot).toMatchFileSnapshot(path)
+}
+
+async function setupSnapshot(
+  options: TuiHarnessOptions = {},
+  size: { columns?: number; rows?: number } = {},
+): Promise<SnapshotHarness> {
+  const terminal = new HeadlessTerminal(size.columns ?? 96, size.rows ?? 36)
+  const before = terminal.frames
+  const result = await createTuiTestHarness(terminal, () => {}, {
+    ...options,
+    cwd: options.cwd === undefined ? '/workspace/project' : options.cwd,
+    config: Object.assign({
+      welcome: 'Snapshot agent ready.',
+      color: true,
+      title: 'DSH snapshot',
+    }, options.config),
+  })
+  await terminal.waitForFrame(before)
+  return result
+}
+
+async function renderAfter(harness: SnapshotHarness, action: () => void): Promise<void> {
+  const before = harness.terminal.frames
+  action()
+  await harness.terminal.waitForFrame(before)
+}
+
+async function disposeSnapshot(harness: SnapshotHarness): Promise<void> {
+  await disposeTuiTestHarness(harness)
+  await harness.terminal.dispose()
+}
+
+async function configureAdvancedTools(ctx: Context): Promise<void> {
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry, { mode: 'code' })
+  ctx.provide('workflows', {} as never)
+  await ctx.plugin(ToolWorkflow, { toolName: 'workflow', maxResultChars: 50_000 })
+  await ctx.plugin(ToolCordis, { vmTimeoutMs: 5_000 })
+}
+
+interface ToolCallFixture {
+  id: string
+  name: string
+  arguments: unknown
+}
+
+function appendToolCalls(session: Session, calls: readonly ToolCallFixture[]): void {
+  appendAssistant(session, calls.map(call => ({
+    type: 'tool-call',
+    id: CallId(call.id),
+    name: call.name,
+    arguments: JSON.stringify(call.arguments),
+  })))
+  for (const call of calls) {
+    session.append('tool/call', {
+      turn: 1,
+      step: 0,
+      callId: CallId(call.id),
+      name: call.name,
+      arguments: JSON.stringify(call.arguments),
+    })
+  }
+}
+
+function appendToolResult(
+  session: Session,
+  id: string,
+  content: ContentBlock[],
+  options: { isError?: boolean; meta?: unknown } = {},
+): void {
+  session.append('tool/result', {
+    turn: 1,
+    step: 0,
+    callId: CallId(id),
+    content,
+    isError: options.isError ?? false,
+    ...options.meta === undefined ? {} : { meta: options.meta },
+  }, { surfaceOp: 'append' })
+}
+
+function visualTool(
+  name: string,
+  call: NonNullable<ToolDefinition['presentCall']>,
+  result?: NonNullable<ToolDefinition['presentResult']>,
+): ToolDefinition {
+  return {
+    name,
+    description: `${name} snapshot fixture`,
+    parameters: {},
+    execute: () => Promise.resolve([]),
+    presentCall: call,
+    ...result === undefined ? {} : { presentResult: result },
+  }
+}
+
+const ADVANCED_CARD_TOOLS: Record<string, ToolDefinition> = {
+  bash: visualTool(
+    'bash',
+    () => ({ card: 'terminal', title: 'pnpm run test:coverage', description: 'Run the coverage gate', cwd: '/workspace/project' }),
+    () => ({ card: 'terminal', output: 'packages/ui/tui 100%\n4016 tests passed\n1 test skipped\ncoverage complete', exitCode: 0 }),
+  ),
+  edit: visualTool(
+    'edit',
+    () => ({ card: 'diff', title: 'Edit renderer', diffs: [{ path: 'src/view.ts', oldText: 'old line', newText: 'new line' }] }),
+    (): ToolResultView => ({
+      card: 'diff',
+      diffs: [
+        { path: 'src/view.ts', oldText: 'old line\nkeep', newText: 'new line\nkeep' },
+        { path: 'tests/view.spec.ts', oldText: null, newText: 'expect(screen).toMatchSnapshot()' },
+      ],
+    }),
+  ),
+  subagent: visualTool('subagent', args => ({
+    card: 'generic',
+    title: 'Delegate renderer audit',
+    rawInput: (args as { prompt: string }).prompt,
+  })),
+  task_output: visualTool('task_output', args => ({
+    card: 'generic',
+    kind: 'read',
+    title: `Read output from background task ${(args as { task_id: string }).task_id}`,
+    rawInput: (args as { task_id: string }).task_id,
+  })),
+  skill: visualTool('skill', args => ({
+    card: 'generic',
+    kind: 'read',
+    title: `Load skill ${(args as { name: string }).name}`,
+    rawInput: (args as { name: string }).name,
+  })),
+}
+
+const CONTROL_PROBE = '\u001b]2;snapshot-controlled\u0007\t\u007f\u009b31m'
+const DISPLAYED_CONTROL_PROBE = String.raw`\x1b]2;snapshot-controlled\x07\x09\x7f\x9b31m`
+
+describe('TUI terminal-state snapshots', () => {
+  it('pins an in-flight reasoning and Markdown stream', async () => {
+    const harness = await setupSnapshot()
+    await renderAfter(harness, () => {
+      appendUser(harness.session, 'Show the live update.')
+      harness.session.append('assistant/chunk', {
+        turn: 2,
+        step: 0,
+        chunk: { type: 'block-start', index: 0, blockType: 'reasoning' },
+      })
+      harness.session.append('assistant/chunk', {
+        turn: 2,
+        step: 0,
+        chunk: { type: 'reasoning-delta', index: 0, text: 'Inspecting width and styles.' },
+      })
+      harness.session.append('assistant/chunk', {
+        turn: 2,
+        step: 0,
+        chunk: { type: 'block-start', index: 1, blockType: 'text' },
+      })
+      harness.session.append('assistant/chunk', {
+        turn: 2,
+        step: 0,
+        chunk: { type: 'text-delta', index: 1, text: 'Streaming **visible state**…' },
+      })
+    })
+    await checkpoint('conversation-streaming', harness.terminal)
+    await disposeSnapshot(harness)
+  })
+
+  it('pins Code Mode run_code with its production presenter', async () => {
+    const harness = await setupSnapshot({ configureContext: configureAdvancedTools })
+    const call = {
+      id: 'code-1',
+      name: 'run_code',
+      arguments: {
+        code: "const first = await tools.bash({ command: 'echo CODE_ONE' })\nconst second = await tools.bash({ command: 'echo CODE_TWO' })\nconsole.log(first, second)\nreturn `${first}+${second}`",
+      },
+    }
+    await renderAfter(harness, () => { appendToolCalls(harness.session, [call]) })
+    await checkpoint('code-mode-pending', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
+
+  it('pins a dynamic workflow with phases, parallel agents, and structured output', async () => {
+    const harness = await setupSnapshot({ configureContext: configureAdvancedTools })
+    const call = {
+      id: 'workflow-1',
+      name: 'workflow',
+      arguments: {
+        meta: {
+          name: 'tui-matrix',
+          description: 'Audit terminal states from independent angles',
+          phases: [
+            { title: 'Inspect', detail: 'Map renderer branches' },
+            { title: 'Verify', detail: 'Challenge missing states', provider: 'deepseek', model: 'deepseek-v4-flash' },
+          ],
+        },
+        args: { packages: ['ui/tui', 'workflow/tool-workflow'] },
+        script: "phase('Inspect')\nconst reports = await parallel([\n  () => agent('Audit layout', { label: 'layout', phase: 'Inspect' }),\n  () => agent('Audit lifecycle', { label: 'lifecycle', phase: 'Inspect' }),\n])\nphase('Verify')\nreturn { reports, verdict: 'covered' }",
+      },
+    }
+    await renderAfter(harness, () => { appendToolCalls(harness.session, [call]) })
+    await checkpoint('dynamic-workflow-pending', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
+
+  it('pins cordis inspect, dynamic mount, and unmount cards with production presenters', async () => {
+    const harness = await setupSnapshot({ configureContext: configureAdvancedTools })
+    const calls = [
+      { id: 'cordis-1', name: 'cordis_inspect', arguments: { what: 'tools' } },
+      {
+        id: 'cordis-2',
+        name: 'cordis_mount',
+        arguments: { code: "return { name: 'snapshot-marker', apply(ctx) { ctx.provide('snapshotMarker', { ready: true }) } }" },
+      },
+      { id: 'cordis-3', name: 'cordis_unmount', arguments: { id: 'dyn-1' } },
+    ]
+    await renderAfter(harness, () => { appendToolCalls(harness.session, calls) })
+    await checkpoint('cordis-tools-pending', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
+
+  it('pins terminal, diff, subagent, task, skill, collapsed, and expanded cards', async () => {
+    const harness = await setupSnapshot({
+      tools: ADVANCED_CARD_TOOLS,
+      config: { maxToolOutputLines: 3 },
+    }, { columns: 100, rows: 40 })
+    const calls = [
+      { id: 'advanced-1', name: 'bash', arguments: { command: 'pnpm run test:coverage' } },
+      { id: 'advanced-2', name: 'edit', arguments: { file_path: 'src/view.ts' } },
+      { id: 'advanced-3', name: 'subagent', arguments: { prompt: 'Review renderer ownership and report only gaps.' } },
+      { id: 'advanced-4', name: 'task_output', arguments: { task_id: 'subagent-7', wait: true } },
+      { id: 'advanced-5', name: 'skill', arguments: { name: 'dsh-code-review' } },
+    ]
+    await renderAfter(harness, () => {
+      appendToolCalls(harness.session, calls)
+      appendToolResult(harness.session, 'advanced-1', [{ type: 'text', text: 'raw process output' }])
+      appendToolResult(harness.session, 'advanced-2', [{ type: 'text', text: 'edit complete' }])
+      appendToolResult(harness.session, 'advanced-3', [{ type: 'text', text: 'The renderer has explicit lifecycle ownership.' }])
+      appendToolResult(harness.session, 'advanced-4', [{ type: 'text', text: 'audit complete\n[status: completed]' }])
+      appendToolResult(harness.session, 'advanced-5', [{ type: 'text', text: 'Loaded review instructions.' }])
+    })
+    await checkpoint('advanced-cards-collapsed', harness.terminal, { includeScrollback: true })
+
+    await renderAfter(harness, () => { harness.terminal.send('\x0f') })
+    await checkpoint('advanced-cards-expanded', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
+
+  it('renders terminal controls as inert text across transcripts, tools, dialogs, diagnostics, and title', async () => {
+    const tools = {
+      unsafe: visualTool(
+        'unsafe',
+        () => ({
+          card: 'terminal',
+          title: `Unsafe title ${CONTROL_PROBE}`,
+          description: `Unsafe description ${CONTROL_PROBE}`,
+          cwd: `/unsafe/${CONTROL_PROBE}`,
+        }),
+        () => ({
+          card: 'terminal',
+          output: `Unsafe output ${CONTROL_PROBE}`,
+          signal: `SIG${CONTROL_PROBE}`,
+        }),
+      ),
+    }
+    const harness = await setupSnapshot({
+      tools,
+      config: {
+        welcome: `Unsafe welcome ${CONTROL_PROBE}`,
+        title: `Unsafe terminal title ${CONTROL_PROBE}`,
+      },
+      beforeMount(session) {
+        appendUser(session, `Unsafe user ${CONTROL_PROBE}`)
+        appendAssistant(session, [
+          { type: 'reasoning', text: `Unsafe reasoning ${CONTROL_PROBE}` },
+          { type: 'text', text: `Unsafe assistant ${CONTROL_PROBE}` },
+        ])
+        appendToolCalls(session, [{ id: 'unsafe-1', name: 'unsafe', arguments: { value: CONTROL_PROBE } }])
+        appendToolResult(session, 'unsafe-1', [{ type: 'text', text: `Unsafe fallback ${CONTROL_PROBE}` }])
+        session.append('todo/write', {
+          todos: [{ content: `Unsafe todo ${CONTROL_PROBE}`, status: 'in_progress' }],
+        })
+        session.append('context/message', {
+          content: [{ type: 'text', text: `Unsafe context ${CONTROL_PROBE}` }],
+          source: { kind: 'plugin', plugin: `unsafe-${CONTROL_PROBE}` },
+        }, { surfaceOp: 'append' })
+        session.append('prompt/blocked', {
+          content: [{ type: 'text', text: 'blocked' }],
+          source: { kind: 'user' },
+          reason: `Unsafe policy ${CONTROL_PROBE}`,
+        })
+        session.append('turn/end', {
+          turn: 7,
+          reason: { kind: 'error', step: 2, message: `Unsafe turn error ${CONTROL_PROBE}` },
+        })
+      },
+    }, { columns: 100, rows: 34 })
+    expect(harness.terminal.title).toContain(DISPLAYED_CONTROL_PROBE)
+    expect(harness.terminal.title).not.toContain('\u001b')
+    expect(harness.terminal.title).not.toContain('\u009b')
+
+    const controller = new AbortController()
+    const beforeQuestion = harness.terminal.frames
+    const answer = harness.ctx.userInteraction.ask({
+      questions: [{
+        id: 'unsafe-question',
+        header: `Unsafe header ${CONTROL_PROBE}`,
+        question: `Unsafe question ${CONTROL_PROBE}`,
+        options: [{ label: `Unsafe option ${CONTROL_PROBE}`, description: `Unsafe detail ${CONTROL_PROBE}` }],
+      }],
+      signal: controller.signal,
+    })
+    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await harness.terminal.waitForFrame(beforeQuestion)
+    await renderAfter(harness, () => {
+      harness.ctx.emit('agent/error', harness.agent, 8, 3, new Error(`Unsafe live error ${CONTROL_PROBE}`))
+    })
+    await checkpoint('untrusted-controls', harness.terminal, { includeScrollback: true })
+
+    controller.abort()
+    await rejected
+    await disposeSnapshot(harness)
+  })
+
+  it('pins a constrained multi-select question and its validation state', async () => {
+    const harness = await setupSnapshot({
+      config: {
+        maxQuestionOptions: 3,
+        questionDialogWidth: 48,
+        questionDialogMaxHeight: 16,
+      },
+    }, { columns: 56, rows: 20 })
+    const controller = new AbortController()
+    const beforeQuestion = harness.terminal.frames
+    const answer = harness.ctx.userInteraction.ask({
+      questions: [{
+        id: 'coverage',
+        header: 'Coverage',
+        question: 'Which advanced TUI states belong in the required matrix?',
+        multiSelect: true,
+        options: [
+          { label: 'Code Mode', description: 'run_code programs and captured output' },
+          { label: 'Workflows', description: 'phases and parallel agents' },
+          { label: 'Cordis tools', description: 'inspect, mount, and unmount' },
+          { label: 'Compaction', description: 'surface replacement and reflow' },
+        ],
+      }],
+      signal: controller.signal,
+    })
+    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await harness.terminal.waitForFrame(beforeQuestion)
+    await checkpoint('question-dialog', harness.terminal)
+
+    await renderAfter(harness, () => { harness.terminal.send('\r') })
+    await checkpoint('question-dialog-validation', harness.terminal)
+    controller.abort()
+    await rejected
+    await disposeSnapshot(harness)
+  })
+
+  it('pins compaction surface replacement and narrow-to-wide reflow', async () => {
+    let replacementStart = 0
+    let replacementEnd = 0
+    let replacementSources: number[] = []
+    const harness = await setupSnapshot({
+      tools: ADVANCED_CARD_TOOLS,
+      beforeMount(session) {
+        const user = session.append('user/message', {
+          content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping before compaction.' }],
+          source: { kind: 'user' },
+        }, { surfaceOp: 'append' })
+        const assistant = session.append('assistant/message', {
+          turn: 1,
+          step: 0,
+          provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+          content: [{ type: 'tool-call', id: CallId('old-tool'), name: 'bash', arguments: '{}' }],
+        }, { surfaceOp: 'append' })
+        session.append('tool/call', { turn: 1, step: 0, callId: CallId('old-tool'), name: 'bash', arguments: '{}' })
+        const result = session.append('tool/result', {
+          turn: 1,
+          step: 0,
+          callId: CallId('old-tool'),
+          content: [{ type: 'text', text: 'obsolete output that must disappear' }],
+          isError: false,
+        }, { surfaceOp: 'append' })
+        replacementStart = user.seq
+        replacementEnd = result.seq
+        replacementSources = [user.seq, assistant.seq, result.seq]
+      },
+    }, { columns: 80, rows: 24 })
+    await checkpoint('surface-before-compaction', harness.terminal, { includeScrollback: true })
+
+    await renderAfter(harness, () => {
+      harness.session.append('context/message', {
+        content: [{ type: 'text', text: 'Compacted summary: the prior command completed and its details were retired from the active surface.' }],
+        source: { kind: 'plugin', plugin: 'compact' },
+      }, {
+        surfaceOp: { op: 'replace', start: replacementStart, end: replacementEnd },
+        sourceEventSeqs: replacementSources,
+      })
+      harness.terminal.resize(44, 18)
+    })
+    await checkpoint('surface-after-compaction-narrow', harness.terminal, { includeScrollback: true })
+
+    await renderAfter(harness, () => { harness.terminal.resize(104, 30) })
+    await checkpoint('surface-after-compaction-wide', harness.terminal, { includeScrollback: true })
+    await disposeSnapshot(harness)
+  })
+
+  it('pins help, unknown commands, live errors, turn failures, and terminal restoration', async () => {
+    const harness = await setupSnapshot({}, { columns: 92, rows: 32 })
+    await renderAfter(harness, () => {
+      harness.terminal.send('/help')
+      harness.terminal.send('\r')
+      harness.terminal.send('/unknown-advanced-command')
+      harness.terminal.send('\r')
+      harness.ctx.emit('agent/error', harness.agent, 3, 1, new Error('provider stream failed after partial output'))
+      harness.session.append('turn/end', {
+        turn: 3,
+        reason: { kind: 'error', step: 1, message: 'provider stream failed after partial output' },
+      })
+      harness.session.append('turn/end', {
+        turn: 4,
+        reason: { kind: 'interrupted' },
+      })
+    })
+    await checkpoint('errors-and-help', harness.terminal, { includeScrollback: true })
+
+    await harness.controller.dispose()
+    await harness.terminal.flush()
+    await checkpoint('disposed-terminal', harness.terminal, { includeScrollback: true })
+    await harness.ctx.fiber.dispose()
+    await harness.terminal.dispose()
+  })
+})
+
+afterAll(async () => {
+  expect([...observedCheckpoints].sort()).toEqual([...CHECKPOINTS].sort())
+  const files = (await readdir(SNAPSHOTS_DIR))
+    .filter(file => file.endsWith('.golden.txt'))
+    .sort()
+  expect(files).toEqual(CHECKPOINTS.map(name => `${name}.golden.txt`).sort())
+})
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
new file mode 100644
index 0000000000..27200e0fa9
--- /dev/null
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -0,0 +1,939 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Terminal } from '@earendil-works/pi-tui'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore, { SessionId } 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 TuiRuntime,
+} from '../src/index.ts'
+import {
+  appendAssistant,
+  appendUser,
+  createTuiTestHarness,
+  disposeTuiTestHarness,
+  type TuiHarnessOptions,
+} from './harness.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()
+  }
+}
+
+async function tick(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 25))
+}
+
+async function setup(options: TuiHarnessOptions = {}) {
+  const terminal = new FakeTerminal()
+  const exit = vi.fn()
+  const result = await createTuiTestHarness(terminal, exit, {
+    ...options,
+    cwd: options.cwd === undefined ? process.cwd() : options.cwd,
+  })
+  await tick()
+  return result
+}
+
+async function dispose(setupResult: Awaited<ReturnType<typeof setup>>): Promise<void> {
+  await disposeTuiTestHarness(setupResult)
+}
+
+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 home = homedir()
+    const homeResult = await setup({
+      cwd: home,
+      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 childResult = await setup({ cwd: join(home, 'projects', 'dsh-tui') })
+    expect(childResult.terminal.output).toContain(join('~', 'projects', 'dsh-tui'))
+    await dispose(childResult)
+
+    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: unrelatedSession.id, 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,
+      provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+      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] 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('main'))
+    ctx.agents.register({
+      id: session.id, 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, { sessionId: 'late-session', color: false }, { terminal, exit: vi.fn() })
+    expect(terminal.started).toBe(0)
+
+    const otherSession = ctx.sessions.create(SessionId('other-session'))
+    ctx.agents.register({
+      id: otherSession.id, 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: session.id, 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('prints a matching live startup failure and exits instead of waiting forever', 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()
+    const exit = vi.fn()
+    mountTui(ctx, { sessionId: 'main-session', color: false }, { terminal, exit })
+
+    ctx.emit('agent-loop/config-start-failed', SessionId('other-session'), new Error('other failed'))
+    expect(terminal.output).toBe('')
+    expect(exit).not.toHaveBeenCalled()
+    ctx.emit('agent-loop/config-start-failed', SessionId('main-session'), new Error('resume \u001b]2;failure-controlled\u0007'))
+    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: Error: resume \\x1b]2;failure-controlled\\x07\n')
+    expect(exit).toHaveBeenCalledWith(1)
+
+    const session = ctx.sessions.create(SessionId('main-session'))
+    ctx.agents.register({
+      id: session.id, options: {}, session, status: 'idle', ctx,
+      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    })
+    await tick()
+    expect(terminal.started).toBe(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('renders an uncoercible startup failure without escaping the display boundary', 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()
+    const exit = vi.fn()
+
+    mountTui(ctx, { sessionId: 'main-session', color: false }, { terminal, exit })
+    ctx.emit('agent-loop/config-start-failed', SessionId('main-session'), {
+      toString(): string { throw new Error('coercion failed') },
+    })
+
+    expect(terminal.started).toBe(0)
+    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: <unrenderable thrown value>\n')
+    expect(exit).toHaveBeenCalledWith(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: session.id, 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, { sessionId: 'failed-start-session', 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, { sessionId: 'missing' }, runtime)).toThrow('is not running')
+    await ctx.fiber.dispose()
+  })
+})
diff --git a/packages/support/subagent-mock/tsconfig.json b/packages/ui/tui/tsconfig.json
similarity index 70%
rename from packages/support/subagent-mock/tsconfig.json
rename to packages/ui/tui/tsconfig.json
index ccc9fa45ed..3a09f80ad8 100644
--- a/packages/support/subagent-mock/tsconfig.json
+++ b/packages/ui/tui/tsconfig.json
@@ -8,9 +8,6 @@
     "src"
   ],
   "references": [
-    {
-      "path": "../../../vendor/cosmokit"
-    },
     {
       "path": "../../../vendor/cordis"
     },
@@ -20,11 +17,20 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/agent-loop"
+    },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../llm/llm"
     },
     {
-      "path": "../../subagent/subagent"
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../user-interaction"
     }
   ]
 }
diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md
index bd5c5281ca..b758ad09e0 100644
--- 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
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fa43d82945..b54201c207 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -810,6 +810,9 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
+      '@deepseek-ai/dsh-tui':
+        specifier: workspace:^
+        version: link:../../ui/tui
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
         version: link:../../ui/user-interaction
@@ -1658,9 +1661,6 @@ importers:
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
-      '@deepseek-ai/dsh-subagent-mock':
-        specifier: workspace:^
-        version: link:../../support/subagent-mock
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -1772,31 +1772,6 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
-  packages/support/subagent-mock:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: 3.18.0
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: ^1.0.0-rc.5
-        version: 1.0.0-rc.5(cordis@4.0.0-rc.7)(node-addon-require-builtin@0.1.0)
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-subagent':
-        specifier: workspace:^
-        version: link:../../subagent/subagent
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
-
   packages/tasks/tasks:
     devDependencies:
       '@deepseek-ai/dsh-agent':
@@ -2087,6 +2062,55 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/ui/tui:
+    dependencies:
+      '@earendil-works/pi-tui':
+        specifier: 0.80.7
+        version: 0.80.7
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tool-cordis':
+        specifier: workspace:^
+        version: link:../../cordis/tool-cordis
+      '@deepseek-ai/dsh-tool-workflow':
+        specifier: workspace:^
+        version: link:../../workflow/tool-workflow
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-user-interaction':
+        specifier: workspace:^
+        version: link:../user-interaction
+      '@deepseek-ai/dsh-workflow':
+        specifier: workspace:^
+        version: link:../../workflow/workflow
+      '@xterm/headless':
+        specifier: 5.5.0
+        version: 5.5.0
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader)
+
   packages/ui/user-approval:
     dependencies:
       schemastery:
@@ -3089,6 +3113,10 @@ packages:
     engines: {node: '>=22.19.0'}
     hasBin: true
 
+  '@earendil-works/pi-tui@0.80.7':
+    resolution: {integrity: sha512-1B2++fLZfgI3XMzW2BTpuDuam2uyHnUUEmsOvi5R0Ne9RAt59WjFV0G8ozX6l1Xafa9P5Y3eT4aDtRr/v/CUTA==}
+    engines: {node: '>=22.19.0'}
+
   '@emnapi/core@1.10.0':
     resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==}
 
@@ -4585,6 +4613,9 @@ packages:
     resolution: {integrity: sha512-A9gOqLdi6cV4ibazAjcQufGj0B1y/vDqYrcuP6d/6x8P27gRS8643Dj9o1dEKtB6O7fwxb2FgBmJS2mX7gpvdw==}
     engines: {node: '>=14.6'}
 
+  '@xterm/headless@5.5.0':
+    resolution: {integrity: sha512-5xXB7kdQlFBP82ViMJTwwEc3gKCLGKR/eoxQm4zge7GPBl86tCdI0IdPJjoKd8mUSFXz5V7i/25sfsEkP4j46g==}
+
   accepts@2.0.0:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
@@ -5385,6 +5416,10 @@ packages:
     resolution: {integrity: sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==}
     engines: {node: '>=18'}
 
+  get-east-asian-width@1.6.0:
+    resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
+    engines: {node: '>=18'}
+
   get-intrinsic@1.3.0:
     resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
     engines: {node: '>= 0.4'}
@@ -5898,6 +5933,11 @@ packages:
     engines: {node: '>= 20'}
     hasBin: true
 
+  marked@18.0.5:
+    resolution: {integrity: sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -7611,6 +7651,11 @@ snapshots:
       - ws
       - zod
 
+  '@earendil-works/pi-tui@0.80.7':
+    dependencies:
+      get-east-asian-width: 1.6.0
+      marked: 18.0.5
+
   '@emnapi/core@1.10.0':
     dependencies:
       '@emnapi/wasi-threads': 1.2.1
@@ -8863,6 +8908,8 @@ snapshots:
 
   '@xmldom/xmldom@0.9.10': {}
 
+  '@xterm/headless@5.5.0': {}
+
   accepts@2.0.0:
     dependencies:
       mime-types: 3.0.2
@@ -9762,6 +9809,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  get-east-asian-width@1.6.0: {}
+
   get-intrinsic@1.3.0:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -10268,6 +10317,8 @@ snapshots:
 
   marked@16.4.2: {}
 
+  marked@18.0.5: {}
+
   math-intrinsics@1.1.0: {}
 
   mathjax-full@3.2.2:
diff --git a/scripts/demo-code-mode.mjs b/scripts/demo-code-mode.mjs
index edfc26b4d5..7a5e054cc0 100644
--- a/scripts/demo-code-mode.mjs
+++ b/scripts/demo-code-mode.mjs
@@ -1,7 +1,7 @@
 /**
- * Boot the REPL or ACP Code Mode overlay, defaulting to REPL. Each overlay
+ * Boot the REPL, TUI, or ACP Code Mode overlay, defaulting to REPL. Each overlay
  * includes its base example, selects Code Mode, and adds the worker runtime.
- * Both require a DeepSeek API key; unsupported arguments fail with usage.
+ * All require a DeepSeek API key; unsupported arguments fail with usage.
  */
 import { spawn } from 'node:child_process'
 
@@ -10,13 +10,14 @@ import { spawn } from 'node:child_process'
 // Loader's HMR path).
 const UIS = new Map([
   ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/coding-agent/code-mode.cordis.yml']],
+  ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']],
   ['acp', ['--import', 'tsx', 'packages/examples/acp-demo/src/bin.ts', '--config', 'examples/acp-agent/code-mode.cordis.yml']],
 ])
 
 const ui = process.argv[2] ?? 'repl'
 const args = UIS.get(ui)
 if (!args || process.argv.length > 3) {
-  console.error('usage: pnpm run demo:code-mode [repl|acp]')
+  console.error('usage: pnpm run demo:code-mode [repl|tui|acp]')
   process.exit(2)
 }
 
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index daeb439c96..94836eaefd 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -253,7 +253,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'subagent',
     title: 'Subagent provider registry',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-mock'],
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
     consumers: ['tool-subagent'],
     note: 'Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name.',
   },
@@ -440,7 +440,15 @@ const APP_EXAMPLES = [
     title: 'Coding Agent App Composition',
     label: 'examples/coding-agent',
     config: 'examples/coding-agent/cordis.yml',
-    summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+    summary: 'The coding-agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+  },
+  {
+    id: 'tui',
+    rel: 'examples/tui-agent/composition.md',
+    title: 'TUI Agent App Composition',
+    label: 'examples/tui-agent',
+    config: 'examples/tui-agent/cordis.yml',
+    summary: 'The TUI agent reuses the coding-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.',
   },
   {
     id: 'cordis',
@@ -462,13 +470,18 @@ const APP_EXAMPLES = [
 
 type AppExample = typeof APP_EXAMPLES[number]
 
-function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void {
+function renderAppExpansion(lines: string[], appNode: string, pluginName: string, exampleId: string): void {
   const agentCore = nodeId('bundle', 'agent_core')
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
   if (pluginName === '@deepseek-ai/dsh-stdio-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["readline UI<br/>console logger<br/>pre-created main agent"]`)
+    const frontDoor = exampleId === 'tui'
+      ? '@deepseek-ai/dsh-tui<br/>pre-created main agent'
+      : exampleId === 'coding'
+        ? '@deepseek-ai/dsh-stdio<br/>pre-created main agent'
+        : 'dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent'
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["${frontDoor}"]`)
   } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]`)
   }
@@ -496,7 +509,7 @@ function renderAppComposition(example: AppExample): string {
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
     if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
-      renderAppExpansion(lines, pluginNode, plugin.name)
+      renderAppExpansion(lines, pluginNode, plugin.name, example.id)
     }
   }
   lines.push(
@@ -986,6 +999,7 @@ function renderIndex(docs: GraphDoc[]): string {
     'docs/capability-seams.md': 'capability seams and core services',
     'examples/echo-agent/composition.md': 'echo-agent app composition',
     'examples/coding-agent/composition.md': 'coding-agent app composition',
+    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -997,6 +1011,7 @@ function renderIndex(docs: GraphDoc[]): string {
     'docs/capability-seams.md': 'hybrid generated',
     'examples/echo-agent/composition.md': 'hybrid generated',
     'examples/coding-agent/composition.md': 'hybrid generated',
+    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index f178f70e9f..ca69768227 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -19,7 +19,7 @@ import WebService from '@deepseek-ai/dsh-web'
 import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock'
+import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import TaskService from '@deepseek-ai/dsh-tasks'
@@ -39,6 +39,17 @@ import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/tool-catalog.md'
 
+/** Register the descriptor needed to mount schema-producing consumers. */
+function registerCatalogSubagentProvider(ctx: Context, name: string): void {
+  const provider: SubagentProvider = {
+    name,
+    capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+    inheritsParentContext: false,
+    start: () => Promise.reject(new Error('tool-catalog provider cannot start a child')),
+  }
+  ctx.subagents.registerProvider(provider)
+}
+
 /**
  * Tool package plus its hand-maintained boot recipe. The caller mounts the
  * prompt and registry; each recipe supplies only package-specific seams and
@@ -191,8 +202,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     shippedNames: ['subagent', 'subagent_fork'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
-      // Register a scripted provider under the name the tool delegates to.
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
       await ctx.plugin(ToolSubagent, { provider: 'mock' })
     },
     note:
@@ -234,7 +244,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       // subagent provider to satisfy it. The schema does not depend on which
       // provider backs the engine.
       await ctx.plugin(SubagentService)
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
       await ctx.plugin(VmWorkflowEngine, { provider: 'mock' })
       await ctx.plugin(ToolWorkflow)
     },
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 0e82e34e66..b6a92c55f6 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1,5 +1,5 @@
 {
-  "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source symbol it must match verbatim. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.",
+  "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source declaration and original JSDoc it must match. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.",
   "entries": [
     { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
@@ -49,6 +49,7 @@
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" },
 
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 407758afc7..f42c346678 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -66,7 +66,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
   'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
-  'packages/support/subagent-mock': { kind: 'indirect', reason: 'Only dsh-tool-subagent renders its configured test outcome.' },
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
   'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
diff --git a/scripts/verify-type-equiv.ts b/scripts/verify-type-equiv.ts
index 08278a6a8f..585796206c 100644
--- a/scripts/verify-type-equiv.ts
+++ b/scripts/verify-type-equiv.ts
@@ -1,7 +1,8 @@
 /**
  * Verify every `ts type-equiv` block against the source symbol named by the
  * manifest. Blocks and entries have a one-to-one relationship; comparison
- * ignores comments and whitespace but preserves declaration structure.
+ * ignores whitespace and non-JSDoc comments but preserves declaration
+ * structure and every original JSDoc comment.
  */
 
 import { globSync, readFileSync, existsSync } from 'node:fs'
@@ -34,12 +35,8 @@ interface EquivBlock {
   code: string
 }
 
-/**
- * Remove comments and normalize whitespace so prose-only edits do not drift
- * structural copies. This is intentionally not a general tokenizer: repo type
- * declarations do not contain comment delimiters inside string literals.
- */
-function normalize(code: string): string {
+/** Normalize declaration structure independently of comments and whitespace. */
+function normalizeStructure(code: string): string {
   return code
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/(^|[^:])\/\/.*$/gm, '$1')
@@ -47,6 +44,15 @@ function normalize(code: string): string {
     .trim()
 }
 
+/**
+ * Extract normalized JSDoc comments in source order. Type declarations in this
+ * repository do not contain comment delimiters inside string literals.
+ */
+function normalizeJSDoc(code: string): string[] {
+  return [...code.matchAll(/\/\*\*[\s\S]*?\*\//g)]
+    .map(match => match[0].replace(/\s+/g, ' ').trim())
+}
+
 /** Strip source-only export modifiers. */
 function stripExport(code: string): string {
   return code.replace(/^export\s+(default\s+)?/, '')
@@ -54,8 +60,14 @@ function stripExport(code: string): string {
 
 /** Parse the declared symbol name from a type-equiv block body. */
 function blockSymbol(code: string): string | null {
-  const m = /(?:export\s+(?:default\s+)?)?(?:abstract\s+)?(?:interface|type|class|enum)\s+([A-Za-z0-9_]+)/.exec(code)
-  return m?.[1] ?? null
+  const sf = ts.createSourceFile('type-equiv.ts', code, ts.ScriptTarget.Latest, /* setParentNodes */ false, ts.ScriptKind.TS)
+  for (const stmt of sf.statements) {
+    const named =
+      ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
+      || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
+    if (named && stmt.name) return stmt.name.text
+  }
+  return null
 }
 
 /** Extract every ` ```ts type-equiv ` block from one Markdown file. */
@@ -88,11 +100,12 @@ function extractEquivBlocks(docRel: string): EquivBlock[] {
   return blocks
 }
 
-/** The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
+/**
+ * The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
  * null when the symbol is not declared there. Uses the TS parser so it spans
  * interfaces, type aliases (including mapped/generic ones), classes, and enums
- * uniformly, and excludes the leading JSDoc (getStart skips leading trivia)
- * while keeping inline member comments. */
+ * uniformly while including declaration and member JSDoc.
+ */
 function sourceDeclaration(sourceRel: string, symbol: string): string | null {
   const abs = resolve(root, sourceRel)
   const text = readFileSync(abs, 'utf8')
@@ -102,7 +115,13 @@ function sourceDeclaration(sourceRel: string, symbol: string): string | null {
       ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
       || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
     if (named && stmt.name?.text === symbol) {
-      return stripExport(stmt.getText(sf))
+      const declarationStart = stmt.getStart(sf)
+      const jsDoc = ts.getJSDocCommentsAndTags(stmt)
+        .filter(ts.isJSDoc)
+        .map(doc => text.slice(doc.pos, doc.end))
+        .join('\n')
+      const declaration = stripExport(text.slice(declarationStart, stmt.getEnd()))
+      return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
     }
   }
   return null
@@ -178,11 +197,18 @@ for (const e of entries) {
     errors.push(`symbol ${e.symbol} not found in ${e.source} (manifest entry for ${e.doc})`)
     continue
   }
-  if (normalize(decl) !== normalize(stripExport(b.code))) {
+  const doc = stripExport(b.code)
+  const sourceStructure = normalizeStructure(decl)
+  const docStructure = normalizeStructure(doc)
+  const sourceJSDoc = normalizeJSDoc(decl)
+  const docJSDoc = normalizeJSDoc(doc)
+  if (sourceStructure !== docStructure || JSON.stringify(sourceJSDoc) !== JSON.stringify(docJSDoc)) {
     errors.push(
       `DRIFT: ${e.doc}:${b.line} — type-equiv block for ${e.symbol} does not match ${e.source}.\n`
-      + `    source: ${normalize(decl)}\n`
-      + `    doc:    ${normalize(stripExport(b.code))}`,
+      + `    source structure: ${sourceStructure}\n`
+      + `    doc structure:    ${docStructure}\n`
+      + `    source JSDoc:     ${JSON.stringify(sourceJSDoc)}\n`
+      + `    doc JSDoc:        ${JSON.stringify(docJSDoc)}`,
     )
     continue
   }
@@ -190,7 +216,7 @@ for (const e of entries) {
 }
 
 if (errors.length === 0) {
-  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source (1:1 with manifest).`)
+  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source structure and JSDoc (1:1 with manifest).`)
   process.exit(0)
 }
 
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 3b68814f97..c631871672 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -72,13 +72,13 @@
     { "path": "./packages/ui/app-boot" },
     { "path": "./packages/ui/jsonrpc" },
     { "path": "./packages/examples/jsonrpc-demo" },
+    { "path": "./packages/ui/tui" },
     { "path": "./packages/ui/stdio" },
     { "path": "./packages/examples/stdio-demo" },
     { "path": "./packages/support/llm-replay" },
     { "path": "./packages/support/acp-snapshot" },
     { "path": "./packages/support/loader-smoke" },
     { "path": "./packages/subagent/subagent" },
-    { "path": "./packages/support/subagent-mock" },
     { "path": "./packages/subagent/tool-subagent" },
     { "path": "./packages/subagent/subagent-inprocess" },
     { "path": "./packages/subagent/subagent-subprocess" },
diff --git a/tsconfig.json b/tsconfig.json
index 3972949e11..8c8a2531c8 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -83,13 +83,13 @@
     { "path": "./packages/ui/app-boot" },
     { "path": "./packages/ui/jsonrpc" },
     { "path": "./packages/examples/jsonrpc-demo" },
+    { "path": "./packages/ui/tui" },
     { "path": "./packages/ui/stdio" },
     { "path": "./packages/examples/stdio-demo" },
     { "path": "./packages/support/llm-replay" },
     { "path": "./packages/support/acp-snapshot" },
     { "path": "./packages/support/loader-smoke" },
     { "path": "./packages/subagent/subagent" },
-    { "path": "./packages/support/subagent-mock" },
     { "path": "./packages/subagent/tool-subagent" },
     { "path": "./packages/subagent/subagent-inprocess" },
     { "path": "./packages/subagent/subagent-subprocess" },
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 9753176f9d..18127b55ee 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -39,7 +39,11 @@ export default defineConfig({
   // through the root tsconfig paths map; the native option cannot do this.
   plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
   test: {
-    include: ['examples/*/tests/**/*.snapshot.ts', 'packages/sdk/*/tests/**/*.snapshot.ts'],
+    include: [
+      'examples/*/tests/**/*.snapshot.ts',
+      'packages/sdk/*/tests/**/*.snapshot.ts',
+      'packages/ui/tui/tests/**/*.snapshot.ts',
+    ],
     // Each test boots a subprocess; give it room and keep the worker file singular. Replay tests
     // opt into bounded in-file concurrency, while record/refresh stay serial because they write
     // fixtures. The environment knob restores serial replay with value 1 on constrained machines.
diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md
index ca54f39176..66bec18578 100644
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -324,7 +324,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 
 - `session` — the session just entered and announced.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L46)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L47)
 
 ### session/disposed
 
@@ -338,7 +338,7 @@ Emitted once when an announced session leaves the store, including publication r
 
 - `session` — the session that is no longer live in the store.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L56)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L57)
 
 ### session/event
 
@@ -353,7 +353,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 - `session` — the session whose log grew.
 - `event` — the appended event, exactly as recorded.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L68)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L69)
 
 ### session/flush
 
@@ -367,7 +367,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 
 - `session` — the session whose buffered events must reach durable storage.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L78)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L79)
 
 ## subagent/*
 
diff --git a/website/zh-CN/api/harness/sessions.md b/website/zh-CN/api/harness/sessions.md
index e39006dd88..712852fc49 100644
--- a/website/zh-CN/api/harness/sessions.md
+++ b/website/zh-CN/api/harness/sessions.md
@@ -7,7 +7,7 @@
 In-memory session store (`ctx.sessions`).
 Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L585)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L577)
 
 ### ctx.sessions.create(id?, options?)
 
@@ -23,7 +23,7 @@ For an agent whose session must be torn down IN ORDER with its loop (so the loop
 
 **Returns** the live session, already entered and announced.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L614)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L606)
 
 ### ctx.sessions.prepare(id?, options?)
 
@@ -38,7 +38,7 @@ Build a session WITHOUT entering it into the store — validate the id/cwd and c
 
 **Returns** the constructed session, NOT yet in the store.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L643)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L635)
 
 ### ctx.sessions.enter(session)
 
@@ -53,7 +53,7 @@ Re-checks the id for a duplicate: `prepare` and `enter` are public cross-package
 
 **Returns** the detach disposer (publication hooks + store removal). When called from a synchronous `session/created` listener, removal and disposal wait until that creation dispatch unwinds.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L687)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L679)
 
 ### ctx.sessions.announce(session)
 
@@ -65,7 +65,7 @@ Emit `session/created` exactly once for an entered session (with the carrier ent
 
 - `session` — the entered session to announce to listeners.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L742)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L734)
 
 ### ctx.sessions.flush(session)
 
@@ -79,7 +79,7 @@ Dispatch the awaited `session/flush` durability checkpoint for `session`, with t
 
 **Returns** resolves when every flush listener has settled; after all settle, rejects with the first registered listener failure if any listener failed.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L794)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L786)
 
 ### ctx.sessions.get(id)
 
@@ -93,7 +93,7 @@ Look up a live session.
 
 **Returns** the session, or undefined when no live session has that id.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L826)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L818)
 
 ### ctx.sessions.list()
 
@@ -105,7 +105,7 @@ All live sessions, in creation order.
 
 **Returns** a fresh array; mutating it does not affect the store.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L834)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L826)
 
 ### ctx.sessions.fork(source, boundary?, childSessionId?)
 
@@ -121,4 +121,4 @@ Create a live child session from a turn-enclosed prefix of a live source. `bound
 
 **Returns** The created live child session.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L851)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L843)