feat(tui): personal TUI rework, integrating upstream model reasoning-effort selection

Consolidates the personal dsh-tui customizations (module split into
components/session/extension, prompt template + running-glyph indicator,
copyable transcript, tool-card headers, timing placement, XML tool output,
status/footer rework) and ports upstream's model reasoning-effort selector
(Shift+Tab effort cycling, effort-aware /model, footer, and /status) onto
the personal module layout.

.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.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-23-tui-generic-card-markdown.md: 494ba580480fa99de54e84025a65bf4589d410f2
+2026-07-23-tui-generic-card-markdown.zh.md: 214edd00f50b88a4e8901b19dcdafc7382399831

.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI generic-card Markdown rendering
+
+Status: implemented
+
+English | [中文](2026-07-23-tui-generic-card-markdown.zh.md)
+
+## Problem
+
+Tool presenters can put Markdown in generic-card content, including fenced `console` output used for background-task acknowledgements and execution errors. Rendering that content as plain text exposes the fence markers and diverges from assistant and user content in the same transcript.
+
+## Decision
+
+The TUI renders generic-card result content with its shared Markdown theme before applying the card's head-and-tail line limit. Terminal and diff cards retain their specialized plain-text renderers, and generic-card raw input remains literal because it represents tool arguments rather than presenter-authored prose.
+
+The shared theme hides fence syntax, retains the optional language label, and colors the fenced body as code. Rendering precedes truncation so collapsed-card line counts and boundaries describe the visible terminal rows rather than Markdown source rows.
+
+## Alternatives considered
+
+**Strip fences in the Bash presenter.** This would fix one producer while leaving generic-card Markdown from other tools unrendered and would make the presenter depend on TUI behavior.
+
+**Render every tool card as Markdown.** Terminal output and diffs have dedicated formatting and may contain Markdown punctuation that must remain literal.
+
+**Apply the collapsed-card limit before Markdown rendering.** Source-line truncation can split a fenced block and makes the visible line count differ from the count used by the card.
+
+## Consequences
+
+Generic tool cards use the same Markdown vocabulary and sanitization path as conversation content. Markdown punctuation in a generic card is interpreted rather than always displayed literally; tools that require literal terminal output use the terminal card intent.
+
+The focused TUI test pins hidden fences, retained language labels, and body text. The keyless terminal-state snapshot covers the behavior through an assembled TUI transcript.

.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.zh.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI 通用卡片的 Markdown 渲染
+
+Status: implemented
+
+[English](2026-07-23-tui-generic-card-markdown.md) | 中文
+
+## Problem
+
+工具展示器可以在通用卡片（generic card）内容中写入 Markdown，其中包括用于后台任务确认和执行错误的围栏 `console` 输出。把这些内容按纯文本渲染会暴露围栏标记，并与同一 transcript（文本记录）中的助手内容和用户内容显示不一致。
+
+## Decision
+
+TUI 先用共享的 Markdown 主题渲染通用卡片的结果内容，再应用卡片的头尾行数限制。终端卡片和 diff 卡片保留各自专门的纯文本渲染器；通用卡片的原始输入仍按字面显示，因为它代表的是工具参数，而非展示器撰写的行文。
+
+共享主题隐藏围栏语法，保留可选的语言标签，并将围栏正文按代码配色。渲染先于截断执行，因此收起状态卡片的行数和边界描述的是可见的终端行，而非 Markdown 源文本行。
+
+## Alternatives considered
+
+**在 Bash 展示器中剥除围栏。**这只修复一个生产方，其他工具产生的通用卡片 Markdown 仍不会被渲染，还会让展示器依赖 TUI 的行为。
+
+**把每种工具卡片都按 Markdown 渲染。**终端输出和 diff 有专门的格式，且可能包含必须保持字面显示的 Markdown 标点。
+
+**在 Markdown 渲染之前应用收起状态卡片的行数限制。**按源文本行截断可能从中间截断围栏块，还会让可见行数与卡片使用的行数不一致。
+
+## Consequences
+
+通用工具卡片与对话内容使用同一套 Markdown 词汇和净化路径。通用卡片中的 Markdown 标点会被解释，而不再总是按字面显示；需要字面终端输出的工具使用终端卡片这一渲染意图。
+
+聚焦的 TUI 测试固定了隐藏的围栏、保留的语言标签和正文文本。无密钥的终端状态快照通过组装后的 TUI transcript 覆盖该行为。

.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.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-24-tui-turn-end-stop-reason-notices.md: 7c783ce5a347b15d682dbeca03ad5355aca7950b
+2026-07-24-tui-turn-end-stop-reason-notices.zh.md: 4a983525779b96c296ac2d621ca5928e7bed61c9

.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md

@@ -0,0 +1,27 @@
+# Agent Note: TUI presents a reason for every turn-end kind
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-turn-end-stop-reason-notices.zh.md)
+
+## Problem
+
+The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejected`, and `interrupted` turn ends, but a `disposed` turn end and any plugin-added `TurnEndReasonMap` kind rendered nothing. When such a turn ended — live or replayed from a persisted log — the agent stopped working with no visible reason, breaking the product expectation that every stop is explained to the user.
+
+## Decision
+
+The `turn/end` case in `packages/ui/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
+
+## Alternatives considered
+
+**A notice for `completed` turns too.** Rejected as noise: every ordinary response would gain a redundant line, and the assistant message plus its frozen timing header already mark the completion.
+
+**Suppressing the `disposed` turn-end notice live because `agent/disposed` also appends `Agent "<id>" was disposed.`** Rejected: the two notices state different facts (this turn was cut short vs. the agent is gone), and the turn-end notice is the only one that survives replay of a persisted log, where the live `agent/disposed` emission does not recur.
+
+**Keeping the default branch silent (the prior behavior).** Rejected: a merge-extensible kind unknown to the TUI is exactly the case where the user has no other way to learn why the agent stopped.
+
+## Consequences
+
+- A turn never ends without a user-visible reason in the TUI: every non-`completed` `turn/end` kind appends a transcript notice, including unknown plugin-added kinds by name.
+- Live disposal during a running turn shows two notices (the turn-end notice plus `agent/disposed`); a replayed log shows the turn-end notice alone.
+- The `errors-and-help` snapshot pins the `disposed` and unknown-kind notices alongside the existing failure and interruption notices.

.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: TUI 为每种轮次结束 kind 呈现原因
+
+Status: implemented
+
+[English](2026-07-24-tui-turn-end-stop-reason-notices.md) | 中文
+
+## 问题
+
+TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这几种轮次结束渲染 transcript（文本记录）通知，但 `disposed` 轮次结束和任何插件新增的 `TurnEndReasonMap` kind 不渲染任何内容。此类轮次结束时，无论实时发生还是从持久化日志回放，agent（智能体）都会在没有任何可见原因的情况下停止工作，违背了「每次停止都要向用户解释」的产品预期。
+
+## 决策
+
+`packages/ui/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
+
+## 备选方案
+
+**为 `completed` 轮次也加一条通知。** 否决，属于噪音：每次普通响应都会平添一行冗余内容，而助手消息加上已冻结的计时头部本就标示了完成。
+
+**因为 `agent/disposed` 也会追加 `Agent "<id>" was disposed.`，就在实时场景下抑制 `disposed` 轮次结束通知。** 否决：两条通知陈述的是不同事实（前者说明这一轮被中途截断，后者说明 agent 已不复存在），而且只有轮次结束通知在回放持久化日志时得以保留，实时发出的 `agent/disposed` 不会在回放中重现。
+
+**让 default 分支保持沉默（沿用先前行为）。** 否决：TUI 不认识的 merge 扩展 kind，恰恰是用户没有其他途径得知 agent 为何停止的情形。
+
+## 后果
+
+- 在 TUI 中，轮次结束永远不会缺少用户可见的原因：每种非 `completed` 的 `turn/end` kind 都会追加一条 transcript 通知，未知的插件新增 kind 也会按名称列明。
+- 轮次运行期间实时 dispose（资源释放）会显示两条通知（轮次结束通知加上 `agent/disposed`）；回放日志则只显示轮次结束通知。
+- `errors-and-help` 快照把 `disposed` 通知和未知 kind 通知连同现有的失败与中断通知一并固定下来。

.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.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 .agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.md
+2026-07-27-tool-card-single-row-fields-inline.md: e04110ed74b68afffc6ea45fc2cb52c4063268e7
+2026-07-27-tool-card-single-row-fields-inline.zh.md: ac532ec6eb51d42a529e0816d1204cb2729a074a

.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.md

@@ -0,0 +1,23 @@
+# Agent Note: Tool-card single-row fields render inline
+
+Status: implemented
+
+English | [中文](2026-07-27-tool-card-single-row-fields-inline.zh.md)
+
+## Problem
+
+A tool card's title, description, cwd, and pending `$ <command>` echo are each one logical row. The bash tool sets the card title (and description) directly from the model's command and description, which for a multi-line bash script contain real newlines. These fields were escaped with `displayText`, which deliberately preserves `\n` as structural layout. A multi-line title therefore broke onto extra terminal rows that the card's line accounting did not reserve, so the title's later lines overwrote the description, the output, or the editor's steering hint — the card rendered as garbled, overlapping text. Removing the gutter bar (see the [copyable-transcript note](../simplification/2026-07-27-copyable-transcript-no-gutter-bar.md)) made the collision visible because those rows no longer sat behind a per-line prefix.
+
+## Decision
+
+Single-row card fields use `displayInlineText` (which escapes `\n` to the literal `\x0a`) instead of `displayText`: the card title, the terminal-card `description` and `cwd` meta rows, and the pending `$ <command>` echo. Each stays on exactly one row, so a multi-line command can no longer break rows and collide with adjacent lines. Genuinely multi-line fields — captured command output and the `contentText` result body — keep `displayText` plus `split('\n')`, because those legitimately occupy multiple rows.
+
+## Alternatives considered
+
+- **Strip newlines from the presenter output** (in the bash tool) — hides the model's real command shape from any consumer of the view, and pushes a UI concern into the tool. The escape belongs at the single-row render site.
+- **Let the title wrap to multiple rows deliberately** — a card title is a one-line identity; a wrapped multi-line title still collides with the following meta rows unless the whole card is re-laid-out, and it bloats the transcript.
+
+## Consequences
+
+- Multi-line bash commands render as a single inline title (`S=/tmp\x0aecho …`); the description, output, and exit rows below stay intact. Verified live in tmux for both the pending (`◌`) and completed (`✓`) states.
+- A `multilineTerminal` tool-card case in `tui.spec.ts` asserts the inline-escaped form appears for a newline-bearing title and description.

.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.zh.md

@@ -0,0 +1,23 @@
+# Agent Note: 工具卡片的单行字段以内联方式渲染
+
+Status: implemented
+
+[English](2026-07-27-tool-card-single-row-fields-inline.md) | 中文
+
+## Problem
+
+工具卡片的标题、描述、cwd 以及待执行的 `$ <command>` 回显各自都是一个逻辑行。bash 工具直接用模型给出的命令与描述来设置卡片标题（和描述），而对于多行 bash 脚本，这些内容包含真实换行。这些字段此前用 `displayText` 转义，而 `displayText` 会刻意保留 `\n` 作为结构性布局。于是多行标题会换到卡片行数核算未预留的额外终端行上，标题后续的行便覆盖了描述、输出，或编辑器的 steering 提示——卡片渲染成互相重叠的乱码文本。移除 gutter bar（见[可复制 transcript 的 note](../simplification/2026-07-27-copyable-transcript-no-gutter-bar.md)）后，这些行不再位于逐行前缀之后，因而暴露了这一冲突。
+
+## Decision
+
+单行卡片字段改用 `displayInlineText`（将 `\n` 转义为字面量 `\x0a`）而非 `displayText`：包括卡片标题、terminal 卡片的 `description` 与 `cwd` 元数据行，以及待执行的 `$ <command>` 回显。每个字段都严格保持在一行内，因此多行命令不再会换行并与相邻行冲突。真正多行的字段——捕获的命令输出与 `contentText` 结果正文——仍保留 `displayText` 加 `split('\n')`，因为它们本就应占据多行。
+
+## Alternatives considered
+
+- **在 presenter 输出中剥除换行**（在 bash 工具里）—— 会对该视图的所有消费方隐藏模型真实的命令形态，并把 UI 关注点塞进工具。转义应发生在单行渲染处。
+- **让标题刻意换到多行** —— 卡片标题是一行式身份标识；除非重排整个卡片，多行标题仍会与其后的元数据行冲突，还会让 transcript 膨胀。
+
+## Consequences
+
+- 多行 bash 命令渲染为单行内联标题（`S=/tmp\x0aecho …`）；其下的描述、输出与退出码行保持完整。已在 tmux 中对待执行（`◌`）与已完成（`✓`）两种状态实测验证。
+- `tui.spec.ts` 中新增了一个 `multilineTerminal` 工具卡片用例，断言对含换行的标题与描述会出现内联转义后的形式。

.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.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 .agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md
+2026-07-27-tui-diff-card-redundant-path-header.md: 708e543ff079828b4929d2a50ac697a9c846608a
+2026-07-27-tui-diff-card-redundant-path-header.zh.md: 863868ae707f37689bbc202267c5470d8c3163e9

.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md

@@ -0,0 +1,37 @@
+# Agent Note: TUI diff card dropped the duplicated file path
+
+Status: implemented
+
+English | [中文](2026-07-27-tui-diff-card-redundant-path-header.zh.md)
+
+## Problem
+
+The `edit` and `write` tool cards printed the target path twice. Each tool's `presentCall`/`presentResult` returns a diff card whose title is `Edit <path>`/`Write <path>` and whose single `FileDiff` carries the same `path`. The TUI's `diffLines` unconditionally rendered `palette.bold(diff.path)` as a per-file header, so a one-file edit rendered:
+
+```
+✓ Edit src/foo.ts
+src/foo.ts
+- old
++ new
+```
+
+The existing snapshot fixture hid the bug: it titled the edit card `Edit renderer` (no path) and gave the result two diffs, so the title never matched a diff path and the header never looked redundant.
+
+## Decision
+
+`diffLines` takes a `showPath` flag; `ToolCardComponent.renderBody` suppresses the per-file header for a diff card when there is exactly one diff and the effective card title (`resultView?.title ?? callView.title`) already contains that diff's path. Multi-file diff cards keep every per-file header. An empty or blank diff path collapses under the same `String.includes` check, which is the intended noise removal.
+
+The suppression lives in the TUI renderer, not in each tool's presenter, because the redundancy is a presentation concern shared by every current and future single-file diff card; the tools keep emitting the path in both the title and the diff so non-TUI consumers still get it.
+
+## Alternatives considered
+
+- Drop the path from the `edit`/`write` card titles. Rejected: the title is the scannable summary line; removing the path weakens it, and it would have to be repeated per tool.
+- Always drop the per-file header. Rejected: multi-file result diffs (and any future multi-file diff card) genuinely need per-file headers.
+
+## Consequences
+
+The heuristic is a substring match, so a title that happens to contain a single diff's path suppresses the header even if the match is incidental; for the real producers the title is exactly `Verb <path>`, so this is correct in practice. The snapshot `edit` fixture now mirrors production: one diff whose path the title names, proving the header is dropped, while multi-file header retention is covered by the `tui.spec.ts` `edit` fixture (`a.txt`/`b.txt` under an `Edit files` title).
+
+## Testing
+
+`tui.spec.ts` adds a focused case asserting the path appears exactly once for a single-diff card titled `Edit src/only.ts`. The `advanced-cards-*` keyless snapshots re-recorded to show the title line immediately followed by the diff body with no repeated path header.

.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md

@@ -0,0 +1,37 @@
+# Agent Note: TUI diff 卡片重复打印文件路径
+
+Status: implemented
+
+[English](2026-07-27-tui-diff-card-redundant-path-header.md) | 中文
+
+## Problem
+
+`edit` 与 `write` 工具卡片会把目标路径打印两次。两者的 `presentCall`/`presentResult` 返回的 diff 卡片，标题为 `Edit <path>`/`Write <path>`，而其唯一的 `FileDiff` 又携带相同的 `path`。TUI 的 `diffLines` 无条件地将 `palette.bold(diff.path)` 渲染为每文件的表头，因此单文件编辑会渲染成：
+
+```
+✓ Edit src/foo.ts
+src/foo.ts
+- old
++ new
+```
+
+既有的快照 fixture 掩盖了这个问题：它把编辑卡片标题设为 `Edit renderer`（不含路径），并让结果包含两个 diff，于是标题从未与某个 diff 路径匹配，表头也就不显得冗余。
+
+## Decision
+
+`diffLines` 新增 `showPath` 参数；当一个 diff 卡片只有一个 diff、且生效标题（`resultView?.title ?? callView.title`）已包含该 diff 的路径时，`ToolCardComponent.renderBody` 抑制每文件表头。多文件 diff 卡片保留全部每文件表头。空白或空路径同样落入这条 `String.includes` 判定之下，这正是有意去除的噪声。
+
+抑制逻辑放在 TUI 渲染层，而非各工具的 present 方法中，因为这种冗余是所有当前及未来单文件 diff 卡片共有的展示问题；工具仍在标题和 diff 中同时给出路径，从而非 TUI 消费方依旧能拿到它。
+
+## Alternatives considered
+
+- 从 `edit`/`write` 卡片标题中去掉路径。已否决：标题是可快速扫读的摘要行，去掉路径会削弱它，而且需要在每个工具里重复处理。
+- 一律去掉每文件表头。已否决：多文件结果 diff（以及未来任何多文件 diff 卡片）确实需要每文件表头。
+
+## Consequences
+
+该启发式是子串匹配，因此若标题恰好包含某个单一 diff 的路径，即便是偶然匹配也会抑制表头；对真实的产出方而言标题恰为 `Verb <path>`，故在实践中是正确的。快照 `edit` fixture 现在与生产一致：单个 diff，其路径正是标题所命名，从而证明表头被去除；而多文件表头保留由 `tui.spec.ts` 的 `edit` fixture（`Edit files` 标题下的 `a.txt`/`b.txt`）覆盖。
+
+## Testing
+
+`tui.spec.ts` 新增一个聚焦用例，断言标题为 `Edit src/only.ts` 的单 diff 卡片中路径恰好出现一次。`advanced-cards-*` 无密钥快照已重新录制，展示标题行紧接 diff 正文、不再有重复的路径表头。

.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.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-27-tui-step-timing-trails-tool-cards.md: 82f46b44d3b939ca89c4508eb948ed584082d9fd
+2026-07-27-tui-step-timing-trails-tool-cards.zh.md: 885b232973d20013782dee7ec1e846e7a012b01e

.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.md

@@ -0,0 +1,28 @@
+# Agent Note: TUI step timing trails the step's last message
+
+Status: implemented
+
+English | [中文](2026-07-27-tui-step-timing-trails-tool-cards.zh.md)
+
+## Problem
+
+The per-step timing summary (`Model wait … · Completed …`) was a child of the assistant message component, so it rendered directly under the assistant text. When a step drove tool calls, the tool cards were appended to the chat *after* the assistant message, leaving the timing line stranded above them — one message before the step's actual last output. The summary is meant to close a step, so on any tool-calling step it appeared in the wrong place.
+
+## Decision
+
+The timing summary is its own `StepTimingComponent`, no longer a child of `AssistantMessageComponent`. `StreamingAssistantComponent` owns one and exposes it as `timing`, but the renderer attaches it to the chat as a sibling that follows the assistant message. Whenever a `tool/call` or `tool/result` of the open step appends a card, `trailStreamingTiming()` moves the footer back to the tail of the chat, so it always trails the step's last message. On `step/end` the footer is completed in place — already at the tail — and stays pinned while the next step's output follows. `removeStreaming` and the reasoning-toggle rebuild detach and reattach the footer together with its streaming component.
+
+Event ordering makes this exact: within a step the loop appends `tool/call` and `tool/result` before `step/end`, so the footer is repositioned while `streaming` is still set, then frozen when the step ends.
+
+## Alternatives considered
+
+**Keep the timing inside the assistant message and reorder tool cards above it.** Rejected: tool cards belong after the assistant text that requested them; moving them above the assistant message to sit under the timing would misrepresent the transcript order.
+
+**Recompute a single trailing footer for the whole turn instead of one per step.** Rejected: a multi-step turn shows each step's own completed timing, and collapsing them would drop the per-step buckets the existing timing tests pin.
+
+**Reposition the footer from a `step/end`-only handler.** Rejected: tool cards render before `step/end`, so a footer moved only at step end would already be trailing but would not track a mid-step re-render, and the running (pre-completion) footer would still sit above the tool cards during streaming.
+
+## Consequences
+
+- On a tool-calling step the timing summary renders below the tool cards, both while the turn runs and after it completes; the package snapshots (`untrusted-controls`, `cordis-tools-pending`, `advanced-cards-*`, `code-mode-pending`, `dynamic-workflow-pending`, `surface-before-compaction`) and the example transcripts (`todo-plan`, `bash-terminal-card`, `code-mode`, `parallel-file-reads`, `dynamic-workflow`, `cordis-dynamic-toolchain`, `code-mode-dispatch-spill`) pin the new order.
+- A unit test asserts the completed timing appears after a step's tool output; it fails on the pre-fix ordering.

.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.zh.md

@@ -0,0 +1,28 @@
+# Agent Note: TUI 步骤计时跟在该步骤最后一条消息之后
+
+Status: implemented
+
+[English](2026-07-27-tui-step-timing-trails-tool-cards.md) | 中文
+
+## 问题
+
+每步的计时摘要（`Model wait … · Completed …`）原本是助手消息组件的子节点，因此直接渲染在助手文本下方。当某一步触发 tool call 时，tool card（工具卡片）会在助手消息*之后*追加到聊天区，使计时行被搁在它们上方——落在该步骤真正的最后一条输出之前一条消息处。该摘要本意是收束一个步骤，因此在任何含 tool call 的步骤上都出现在了错误的位置。
+
+## 决策
+
+计时摘要现在是独立的 `StepTimingComponent`，不再是 `AssistantMessageComponent` 的子节点。`StreamingAssistantComponent` 持有一个并以 `timing` 暴露它，但渲染器把它作为紧随助手消息之后的同级节点挂到聊天区。每当当前打开步骤的 `tool/call` 或 `tool/result` 追加一张卡片，`trailStreamingTiming()` 就把该页脚移回聊天区末尾，使它始终跟在该步骤的最后一条消息之后。在 `step/end` 时该页脚就地定稿——此时已在末尾——并在后续步骤的输出接续时保持钉住。`removeStreaming` 与推理开关重建会把该页脚连同其流式组件一起摘除并重新挂上。
+
+事件顺序让这一点精确成立：在一个步骤内，循环会先追加 `tool/call` 和 `tool/result`，再追加 `step/end`，因此页脚是在 `streaming` 仍被设置时重新定位的，随后在步骤结束时冻结。
+
+## 备选方案
+
+**把计时保留在助手消息内部，改为把 tool card 排到它上方。** 否决：tool card 应位于请求它们的助手文本之后；把它们移到助手消息上方以贴在计时下方，会歪曲 transcript（文本记录）的顺序。
+
+**为整个轮次重算一个末尾页脚，而非每步一个。** 否决：多步轮次会显示各步自己的完成计时，合并它们会丢掉现有计时测试所固定的每步分桶。
+
+**只在 `step/end` 处理器里重新定位页脚。** 否决：tool card 在 `step/end` 之前渲染，因此仅在步骤结束时移动的页脚虽已处于末尾，却无法跟踪步骤中途的重新渲染，而且流式过程中运行态（完成前）的页脚仍会落在 tool card 上方。
+
+## 后果
+
+- 在含 tool call 的步骤上，计时摘要渲染在 tool card 下方，轮次运行期间与完成之后皆如此；相关包快照（`untrusted-controls`、`cordis-tools-pending`、`advanced-cards-*`、`code-mode-pending`、`dynamic-workflow-pending`、`surface-before-compaction`）与示例 transcript（`todo-plan`、`bash-terminal-card`、`code-mode`、`parallel-file-reads`、`dynamic-workflow`、`cordis-dynamic-toolchain`、`code-mode-dispatch-spill`）固定了新顺序。
+- 一个单元测试断言完成计时出现在某步骤的工具输出之后；在修复前的顺序下它会失败。

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml

@@ -1,6 +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: 8d7c7b00c8d9b15ea3f2419ed44ca88209e60dad
-2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 49e9541c9f98c9f3beba11945ff452fc38bd9ede
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
+2026-07-17-dedicated-full-screen-tui-front-door.md: a3f3d6b51e85ad20218ce5aebf526bd96946be55
+2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 6a0c2f12815e9418a2b5bcb237d3db3616ccd133

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md

@@ -20,9 +20,9 @@ The selected front door receives the exact generated or resumed `SessionId` used
 
 ### 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. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle.
+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, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. 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 idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; agent behavior and answer logging remain owned by their existing services.
+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. `/exit` and `/quit` share the same exit path: they cancel an active turn, wait for idle, and then restore and close the terminal. The idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; the panel's controls hint lists only actions meaningful for the current option count, omitting navigation when exactly one option is shown; agent behavior and answer logging remain owned by their existing services.
 
 The `/model` command presents the advisory `ctx.llm` catalog as a keyboard selector and changes only this TUI session's target; argument forms remain available for direct selection. Each model row owns the adapter-advertised reasoning-effort order and default: Shift+Tab cycles that row's efforts, includes provider-default behavior when the adapter advertises no default, and leaves models without selectable metadata unchanged. Agent-scoped prompt-assembly and request waterfalls snapshot one provider/model/reasoning-effort target per step, so `{{provider}}` / `{{model}}` interpolation and request routing cannot split when a command arrives during assembly. The latest logged request header restores a used target; a selection that never reaches a request remains process-local.
 

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md

@@ -20,9 +20,9 @@ DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README
 
 ### 会话投影与交互
 
-TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。
+TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。
 
-agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；agent 行为和答案日志仍由既有服务负责。
+agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。`/exit` 和 `/quit` 共用同一条退出路径：先取消进行中的轮次，等待 agent 空闲，然后恢复并关闭终端。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；面板的操作提示只列出在当前选项数量下有意义的操作，仅有一个选项时不显示导航项；agent 行为和答案日志仍由既有服务负责。
 
 `/model` 命令将建议性的 `ctx.llm` 目录呈现为键盘选择器，并且只更改当前 TUI 会话的目标；带参数的形式仍可直接选择目标。每个模型行都持有适配器公布的推理强度顺序和默认值：按 Shift+Tab 可循环切换该行的推理强度；如果适配器没有公布默认值，循环中还会包含提供方默认行为；没有可选元数据的模型则保持不变。agent 作用域内的 prompt 组装和请求两条 waterfall（瀑布式事件）会为每个步骤快照一次同一个提供方/模型/推理强度目标，因此即使命令在组装期间到达，`{{provider}}` / `{{model}}` 插值与请求路由也不会分裂。系统通过日志中最新的请求头恢复已经使用过的目标；未被请求使用的选择只保留在当前进程中。
 

.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.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-21-tui-skill-slash-command.md: d7532a05fce5605491ce42c87a2a523eb4c19acc
-2026-07-21-tui-skill-slash-command.zh.md: 16930020bd404f7bc9476169cd1d063aa57b5c94
+2026-07-21-tui-skill-slash-command.md: 8370ab61f552a6a60177b6da0b598dd142d21960
+2026-07-21-tui-skill-slash-command.zh.md: 66edec6ecd5c2a974b56e08bd9e924729302cc4a

.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md

@@ -14,7 +14,7 @@ The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door o
 
 The TUI reads the skill service through `ctx.get('skills')`, not a declared injection, because skills mount conditionally: a deployment without the registry keeps a working front door, and `/skill:` there reports that skills are unavailable rather than failing to mount. `createTuiChat` is synchronous while `ctx.skills.list()` is async, so autocomplete seeds the static slash commands immediately and rebuilds the provider with `skill:<name>` entries once the catalog resolves; a resolution that arrives after disposal is dropped, and a rejected lookup keeps the base commands.
 
-Autocomplete lists only model-invocable skills — it is built from `list()`, which omits `disableModelInvocation` skills — while manual submission resolves through `get()`, which the skill registry documents as the trusted-caller path that returns disabled skills too. So a person can load any skill by typing its exact name, but the completion menu never advertises a skill the model is meant not to see. An unknown name, an empty name after the prefix, and a lookup failure each surface as a transcript notice without sending anything.
+Autocomplete lists only model-invocable skills — it is built from `list()`, which omits `disableModelInvocation` skills — while manual submission resolves through `get()`, which the skill registry documents as the trusted-caller path that returns disabled skills too. So a person can load any skill by typing its exact name, but the completion menu never advertises a skill the model is meant not to see. Each completion entry is labeled with its winning source's scope — `(project)` for the `project-` sources, `(user)` for every other source — in the slash-command argument-hint slot, which the menu shows but selection never inserts, so trailing instructions still follow the completed name. An unknown name, an empty name after the prefix, and a lookup failure each surface as a transcript notice without sending anything.
 
 `renderSkillInvocation` and the resource-base line are the TUI's own, deliberately not reused from `dsh-tool-skill`'s `skill` tool result. The tool wraps a body in `<skill_content>`/`<skill_resources>`/`<skill_instructions>` for a *tool result*; a manual invocation is a *user turn*, and coupling the two renderers would force one model-facing shape to serve both surfaces. The cost is two renderers that both format a skill body; the benefit is that each surface's model-facing text evolves independently, and each is pinned where it is produced.
 

.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md

@@ -14,7 +14,7 @@ Status: implemented
 
 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:<name>` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。
 
-自动补全只列出模型可调用的 skill——它基于 `list()` 构建，而 `list()` 会略去 `disableModelInvocation` 的 skill——手动提交则通过 `get()` 解析，skill 注册表将其记录为返回被禁用 skill 的可信调用方路径。因此用户可以通过键入 skill 的确切名称加载任意 skill，但补全菜单绝不会宣传一个本不该让模型看见的 skill。未知名称、前缀之后为空的名称、以及查找失败，都会各自呈现为 transcript（文本记录）中的一条通知，且不发送任何内容。
+自动补全只列出模型可调用的 skill——它基于 `list()` 构建，而 `list()` 会略去 `disableModelInvocation` 的 skill——手动提交则通过 `get()` 解析，skill 注册表将其记录为返回被禁用 skill 的可信调用方路径。因此用户可以通过键入 skill 的确切名称加载任意 skill，但补全菜单绝不会宣传一个本不该让模型看见的 skill。每个补全条目都以其胜出来源的作用域为标签——`project-` 来源标为 `(project)`，其他一切来源标为 `(user)`——标签置于斜杠命令的参数提示位，菜单会显示它，但选中时绝不会插入，因此尾随指令仍然跟在补全后的名称之后。未知名称、前缀之后为空的名称、以及查找失败，都会各自呈现为 transcript（文本记录）中的一条通知，且不发送任何内容。
 
 `renderSkillInvocation` 及资源基址行是 TUI 自有的，刻意不复用 `dsh-tool-skill` 的 `skill` 工具结果。该工具把正文包进 `<skill_content>`/`<skill_resources>`/`<skill_instructions>` 是为了一个*工具结果*；而手动调用是一个*用户轮次*，把两个渲染器耦合起来会迫使一种面向模型的形态同时服务两个界面。代价是两个都在格式化 skill 正文的渲染器；收益是各界面面向模型的文本可以独立演进，且各自在其产出处被固定。
 

.agents/notes/implemented/feature/2026-07-23-tui-footer-session-identity.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-23-tui-footer-session-identity.md: aa17ead4194c52464de0caad86d8611eae94786c
+2026-07-23-tui-footer-session-identity.zh.md: 686c11294ffd02304dc87cd790252a347fe35011

.agents/notes/implemented/feature/2026-07-23-tui-footer-session-identity.md

@@ -0,0 +1,27 @@
+# Agent Note: Keep the TUI session identity visible
+
+Status: implemented
+
+English | [中文](2026-07-23-tui-footer-session-identity.zh.md)
+
+## Problem
+
+The startup banner identifies the active session, but it scrolls out of view during a conversation. Operators working with several resumable sessions then lack a persistent way to confirm which session receives their input.
+
+## Decision
+
+The TUI footer begins with the active session id, before the model, working directory, token counts, cache rate, and context use. It shows tool-card state only while cards are expanded; the default collapsed state adds no label. The session id uses the same control-character escaping as other terminal labels and participates in the footer's existing left-to-right clipping behavior.
+
+The footer reads the id from the mounted agent's session, so fresh and resumed sessions use the same authoritative identity without separate UI state.
+
+## Alternatives considered
+
+- **Keep the identity only in the startup banner** — rejected because the banner leaves the viewport in longer conversations.
+- **Show the session id only in `/status`** — rejected because an on-demand diagnostic does not let an operator confirm identity before sending input.
+- **Put the session id in the right footer segment** — rejected because narrow terminals clip that segment first; session identity is more important than context and expanded tool-card state.
+
+## Consequences
+
+The current session remains identifiable while the editor is active. On narrow terminals, the longer left segment leaves less room for context and the expanded tool-card label, while the existing clipping policy preserves session identity, model, and as much operational context as fits.
+
+Package coverage pins the footer ordering and escaping path, and the runnable TUI terminal snapshots pin the assembled layout.

.agents/notes/implemented/feature/2026-07-23-tui-footer-session-identity.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: 保持 TUI 会话标识可见
+
+[English](2026-07-23-tui-footer-session-identity.md) | 中文
+
+Status: implemented
+
+## Problem
+
+启动横幅会标识当前会话，但在对话过程中会滚出视野。操作多个可恢复会话时，用户因而无法持续确认输入将发送到哪个会话。
+
+## Decision
+
+TUI 页脚以当前会话 id 开头，之后依次显示模型、工作目录、token 用量、缓存命中率和上下文用量。工具卡片状态仅在卡片展开时显示；默认的折叠状态不添加任何标签。会话 id 与其他终端标签采用相同的控制字符转义，并遵循页脚现有的从左到右裁剪行为。
+
+页脚从已挂载 agent 的会话读取 id，因此新建和恢复的会话都使用同一权威标识，无需单独维护 UI 状态。
+
+## Alternatives considered
+
+- **仅在启动横幅中保留标识** — 未采用，因为对话较长时横幅会离开视野。
+- **仅在 `/status` 中显示会话 id** — 未采用，因为按需诊断无法让用户在发送输入前确认会话标识。
+- **将会话 id 放入页脚右侧区域** — 未采用，因为窄终端会优先裁剪该区域；会话标识比上下文和展开的工具卡片状态更重要。
+
+## Consequences
+
+编辑器处于活动状态时，当前会话始终可识别。在窄终端中，更长的左侧区域会减少上下文和展开的工具卡片标签的显示空间；现有裁剪策略会保留会话标识、模型，以及空间允许的其他运行信息。
+
+包级覆盖固定页脚顺序和转义路径，可运行 TUI 的终端快照固定组装后的布局。

.agents/notes/implemented/feature/2026-07-23-tui-status-prompt-tools.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-23-tui-status-prompt-tools.md: 42524d021d0f2786371762b447ad5d195dc828bd
+2026-07-23-tui-status-prompt-tools.zh.md: 5a33e19e9780749a721395a0b07f43790103013c

.agents/notes/implemented/feature/2026-07-23-tui-status-prompt-tools.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI status inspects model request inputs
+
+Status: implemented
+
+English | [中文](2026-07-23-tui-status-prompt-tools.zh.md)
+
+## Problem
+
+Session counters describe activity but do not reveal the instructions and capabilities that the next model request receives. Diagnosing scoped prompt contributions and tool restrictions otherwise requires leaving the TUI or inferring configuration from files.
+
+## Decision
+
+`/status` assembles the current agent's system prompt through `ctx.systemPrompt` and renders it with the same renderer used by the agent loop. After the bordered diagnostics card, separate unbordered `System prompt` and `Registered tools` sections show the rendered prompt and the assembly's ordered tool names, which are the schemas exposed to the model for that agent and presentation mode.
+
+Assembly uses the command's cancellation signal and current agent scope, so scoped sections, variables, tool restrictions, and assembly listeners match a request made at that point. Prompt and tool values are escaped through the TUI's terminal-control sanitizer before rendering. Empty prompt text and an empty tool list render as `(empty)` and `(none)`.
+
+## Alternatives considered
+
+**Read prompt sections and the tool registry independently.** Rejected: that bypasses prompt assembly waterfalls, tool ordering, presentation modes, and per-agent restrictions, so the diagnostics could disagree with the next request.
+
+**Show complete tool schemas.** Rejected: names answer which capabilities are registered without making the status card dominated by parameter JSON; schema details remain available in the generated tool catalog and source definitions.
+
+## Consequences
+
+The command can run prompt providers and assembly listeners, just like request preparation, and reports their failures through the existing command-error notice. The snapshot is point-in-time: a later registration, restriction, mode change, or dynamic provider can alter the next request.
+
+## Testing
+
+Unit coverage pins scoped assembly output, ordered tool names, empty labels, and terminal-control escaping. The keyless TUI smoke and terminal snapshot exercise `/status` through the assembled application.

.agents/notes/implemented/feature/2026-07-23-tui-status-prompt-tools.zh.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI 状态检查模型请求输入
+
+Status: implemented
+
+[English](2026-07-23-tui-status-prompt-tools.md) | 中文
+
+## 问题
+
+会话计数器可以描述活动情况，却无法显示下一次模型请求将收到的指令和能力。若要诊断按作用域贡献的提示词与工具限制，用户只能离开 TUI，或根据配置文件进行推断。
+
+## 决策
+
+`/status` 通过 `ctx.systemPrompt` 为当前 agent（智能体）组装系统提示词，并使用与 agent loop（智能体循环）相同的渲染器完成渲染。在带边框的诊断卡片之后，独立且无边框的 `System prompt` 和 `Registered tools` 区域分别显示渲染后的提示词与 assembly 中按顺序排列的工具名称；这些名称对应当前 agent 与呈现模式向模型公开的 schema。
+
+组装使用命令的取消信号和当前 agent 作用域，因此按作用域注册的 section、变量、工具限制及 assembly listener 与此时发起的请求保持一致。提示词和工具值在呈现前经过 TUI 的终端控制字符净化。空提示词与空工具列表分别显示为 `(empty)` 和 `(none)`。
+
+## 曾考虑的替代方案
+
+**分别读取提示词 section 和工具注册表。** 已否决：该做法会绕过提示词组装 waterfall（瀑布式事件）、工具排序、呈现模式和按 agent 限制，因此诊断结果可能与下一次请求不一致。
+
+**显示完整工具 schema。** 已否决：工具名称足以回答注册了哪些能力，同时避免参数 JSON 占据大部分状态卡片；schema 详情仍可在生成的工具目录和源代码定义中查看。
+
+## 后果
+
+该命令可能像请求准备一样运行提示词提供方与 assembly listener，并通过现有命令错误提示报告失败。结果是一个时点快照：后续注册、限制、模式变更或动态提供方都可能改变下一次请求。
+
+## 测试
+
+单元测试固定按作用域组装的输出、工具名称顺序、空值标签和终端控制字符转义。无密钥 TUI 冒烟测试与终端快照通过完整组装的应用执行 `/status`。

.agents/notes/implemented/feature/2026-07-24-configurable-tui-prompt-theme.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-24-configurable-tui-prompt-theme.md: 4008f23a3f545e9b4484f0fa3f8490ad9b2c5541
+2026-07-24-configurable-tui-prompt-theme.zh.md: daf15b54d7e04d3860eacad47b754b963cde36fa

.agents/notes/implemented/feature/2026-07-24-configurable-tui-prompt-theme.md

@@ -0,0 +1,39 @@
+# Agent Note: TUI prompt themes compose mutable plugin values
+
+Status: implemented
+
+English | [中文](2026-07-24-configurable-tui-prompt-theme.zh.md)
+
+## Problem
+
+The terminal prompt row and editor prefix were assembled inside the TUI from a fixed set of workspace, model, usage, cache, context, and timing fields. Deployments could change colors globally but could not choose field order, replace the input prefix, add plugin state, or build a Powerline prompt.
+
+## Decision
+
+The TUI theme groups `color`, `truecolor`, `leftPrompt`, `rightPrompt`, `inputPrompt`, and the static running-state `inputPlaceholder`. The three prompt strings interpolate `${name}` references; unknown or unavailable values disappear with adjacent horizontal separator whitespace. The left and right templates share one row, retain the right side on overlap, and use ANSI-aware visible widths. The input template controls the first-line editor prefix and continuation indentation.
+
+`ctx.tuiPrompt` is a context-global registry supplied by `@deepseek-ai/dsh-tui/prompt`. `register(name, initialValue)` returns a handle with `set(value)` and `dispose()`. Values are stored strings rather than callbacks: updates are explicit, unchanged strings are ignored, and a registration, mutation, or disposal schedules one coalesced notification. The renderer reads current values with `get(name)` and subscribes with `subscribe(listener)` to learn when to redraw. That subscription is a direct in-service callback, not a Cordis event, so a value changing on its own schedule still repaints without a bus entry other consumers would never use. Both `subscribe` and each registration are owned by the caller's Cordis effect, so they are removed when the subscriber's or contributor's fiber disposes. Each `subscribe` call is a distinct subscription keyed by record identity, so two fibers may pass the same callback and disposing one leaves the other live. The coalesced notification contains every observer — a synchronous throw, a rejected returned promise, and even an error hostile to string rendering (logs go through the non-throwing `errorChain`) — so one broken observer cannot starve the rest, and it re-checks each subscription's liveness during delivery so a listener that synchronously unsubscribes another in the same burst silences it immediately. Registration follows Cordis effect ownership, rejects duplicate names, and removes the value on plugin disposal.
+
+Registered fragments are trusted ANSI-capable presentation output. Template literals and ordinary external content remain sanitized, but a prompt-value plugin may emit terminal controls. Composite values own coordinated background transitions and separators, so one `${powerline}` value can render a complete Powerline segment without coupling adjacent atomic providers.
+
+The built-in `cwd`, `git/worktree`, `token_meter/cache_hit_rate`, `model`, `context`, `timing`, styled `symbol` label, and `indicator` caret values use the same registry. Session and agent events update their handles, while the running timer updates `timing` and the animated `indicator` each tick. The shipped input template is `${symbol} ${indicator}`, preserving the existing `dsh > ` prefix.
+
+## Alternatives considered
+
+**Evaluate synchronous provider callbacks on every render.** Rejected: render-time plugin code adds an avoidable failure boundary; stored strings keep the render pass free of plugin evaluation.
+
+**Publish the change notification as a Cordis event.** Rejected: the notification has exactly one consumer (the TUI renderer for the current session), so a global typed event adds a bus entry, scoped-dispatch surface, and cross-plugin fan-out no one else observes. A direct `subscribe` callback contained inside the service carries the same coalesced redraw with less surface.
+
+**Expose semantic style roles instead of ANSI.** Rejected: semantic roles cannot express arbitrary Powerline background transitions without expanding the shared style protocol for each presentation technique.
+
+**Put prompt fields at the top level of TUI config.** Rejected: templates and color selection jointly define terminal presentation and belong under one `theme` object.
+
+## Consequences
+
+Prompt contributors depend on the TUI-specific registry and are loaded after the service but before the TUI consumer. The namespace is global to the Cordis context, matching the TUI's current single-session transcript ownership. Arbitrary ANSI is intentionally trusted: unsupported cursor-affecting sequences can disrupt layout, and alignment is reliable only for sequences understood by pi-tui's visible-width utilities.
+
+Changing `inputPrompt` through a registered value preserves editor text, cursor, history, completion, and focus because pi-tui supports replacing equal-width first and continuation prefixes in place. The static `inputPlaceholder` is sanitized and appears only while the agent runs and the editor is empty.
+
+## Testing
+
+Registry tests pin validation, duplicate rejection, updates, unavailable values, coalesced-notification containment, unsubscribe, disposal, interpolation, trailing-literal retention, whitespace cleanup, and ANSI preservation. TUI tests pin nested theme defaults, custom templates, out-of-band value redraw, mutable redraw, Powerline-capable fragments, dynamic input-prefix width, and the static running placeholder. The assembled TUI demo test pins service load order and config forwarding.

.agents/notes/implemented/feature/2026-07-24-configurable-tui-prompt-theme.zh.md

@@ -0,0 +1,39 @@
+# Agent Note: TUI 提示符主题组合可变的插件值
+
+Status: implemented
+
+[English](2026-07-24-configurable-tui-prompt-theme.md) | 中文
+
+## 问题
+
+终端提示符行与编辑器前缀原先在 TUI 内部由一组固定字段拼装而成，涵盖工作区、模型、用量、缓存、上下文与计时。部署方可以全局更改颜色，却无法调整字段顺序、替换输入前缀、加入插件状态，也无法构建 Powerline 风格的提示符。
+
+## 决策
+
+TUI 主题把 `color`、`truecolor`、`leftPrompt`、`rightPrompt`、`inputPrompt` 以及运行状态下的静态 `inputPlaceholder` 归为一组。三个提示符字符串通过插值引用 `${name}`；未知或不可用的值连同相邻的横向分隔空白一起消失。左右模板共用一行，重叠时保留右侧，宽度计算使用可识别 ANSI 的可见宽度。输入模板控制编辑器首行前缀与续行缩进。
+
+`ctx.tuiPrompt` 是由 `@deepseek-ai/dsh-tui/prompt` 提供的上下文全局注册表。`register(name, initialValue)` 返回带 `set(value)` 与 `dispose()` 的句柄。存储的值是字符串而非回调：更新必须显式发起，未变化的字符串会被忽略，而一次注册、变更或 dispose 会安排一次合并后的通知。渲染器用 `get(name)` 读取当前值，并用 `subscribe(listener)` 订阅何时重绘。该订阅是服务内部的直接回调，而非 Cordis 事件，因此一个自行变化的值仍能重绘，而不需要一个其他消费方永远不会观察的总线条目。`subscribe` 与每个注册都由调用方的 Cordis effect 拥有，因此在订阅方或贡献方的 fiber dispose 时一并移除。每次 `subscribe` 都是一个按记录身份区分的独立订阅，因此两个 fiber 可以传入同一个回调，而 dispose 其中一个不会影响另一个。合并通知会容错每个观察者——同步抛出、返回被拒 promise，甚至一个对字符串渲染也会抛异常的错误（日志走不抛异常的 `errorChain`）——因此一个损坏的观察者不会饿死其余观察者；并且在派发过程中会重新校验每个订阅的存活性，因此同一批次中同步取消了另一个订阅的监听器会立即使其静默。注册遵循 Cordis 的 effect 所有权模型，拒绝重复名称，并在插件 dispose（资源释放）时移除对应的值。
+
+注册的片段被视为可信的、允许携带 ANSI 的呈现输出。模板中的字面文本与普通外部内容仍会被清洗，但提供提示符值的插件可以输出终端控制序列。复合值自行负责协调背景色过渡与分隔符，因此一个 `${powerline}` 值就能渲染完整的 Powerline 段，而无需与相邻的原子提供方耦合。
+
+内置的 `cwd`、`git/worktree`、`token_meter/cache_hit_rate`、`model`、`context`、`timing`、带样式的 `symbol` 标签与 `indicator` 光标符值使用同一个注册表。会话与 agent（智能体）事件更新各自的句柄，运行计时器每一拍更新 `timing` 与带动画的 `indicator`。随附的输入模板为 `${symbol} ${indicator}`，保留了原有的 `dsh > ` 前缀。
+
+## 曾考虑的替代方案
+
+**每次渲染时求值同步的提供方回调。** 不予采纳：在渲染期执行插件代码会引入一个本可避免的故障边界；存储字符串能让渲染过程不涉及插件求值。
+
+**把变更通知发布为 Cordis 事件。** 已否决：该通知只有一个消费方（当前会话的 TUI 渲染器），因此全局类型事件会增加一个总线条目、scope 分发面以及无人观察的跨插件扇出。服务内部包裹的直接 `subscribe` 回调以更小的面积承载同样的合并重绘。
+
+**暴露语义化的样式角色而非 ANSI。** 不予采纳：语义角色无法表达任意的 Powerline 背景色过渡，除非为每种呈现技巧扩展共享的样式协议。
+
+**把提示符字段放在 TUI 配置顶层。** 不予采纳：模板与颜色选择共同定义终端呈现，应归属于同一个 `theme` 对象之下。
+
+## 后果
+
+提示符值的贡献插件依赖 TUI 专属的注册表，加载顺序位于该服务之后、TUI 消费方之前。命名空间对整个 Cordis 上下文全局生效，与 TUI 当前的单会话 transcript（文本记录）所有权一致。允许任意 ANSI 是有意的信任决策：不受支持的、影响光标的序列可能破坏布局，只有 pi-tui 可见宽度工具能理解的序列才能保证对齐可靠。
+
+通过注册值更改 `inputPrompt` 时，编辑器文本、光标、历史、自动补全与焦点均得以保留，因为 pi-tui 支持原地替换等宽的首行与续行前缀。静态的 `inputPlaceholder` 会被清洗，且仅在 agent 运行且编辑器为空时显示。
+
+## 测试
+
+注册表测试固定校验、重名拒绝、更新、不可用值、合并通知的容错、取消订阅、dispose、插值、尾随字面保留、空白清理与 ANSI 保留等行为。TUI 测试固定嵌套主题默认值、自定义模板、带外值重绘、可变重绘、支持 Powerline 的片段、动态输入前缀宽度以及运行状态下的静态占位文本。组装后的 TUI 演示测试固定服务加载顺序与配置转发。

.agents/notes/implemented/feature/2026-07-24-readable-xml-tool-output.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-24-readable-xml-tool-output.md: 4f7327a7c6f5e2f04e36576da0fb739c34955e8a
+2026-07-24-readable-xml-tool-output.zh.md: 3c56d256b489863210b44449111f03a5752a889a

.agents/notes/implemented/feature/2026-07-24-readable-xml-tool-output.md

@@ -0,0 +1,27 @@
+# Agent Note: Readable XML tool output
+
+Status: implemented
+
+English | [中文](2026-07-24-readable-xml-tool-output.zh.md)
+
+## Problem
+
+Model-facing context and tool result text can expose transport-oriented XML wrappers instead of the information people need. Context producers do not declare presentation intent, and replayed tool calls whose definition is unavailable still need a conservative fallback that does not reinterpret ordinary prose or partial markup.
+
+## Decision
+
+The read tool declares a generic completed-result presentation that removes its `<path>`, `<type>`, and `<content>` wrapper while preserving the numbered content and footer. This tool-owned projection applies consistently to every UI that consumes tool presentation intent.
+
+The TUI parses a context message or unavailable-tool result as XML only when the complete text is one supported XML document. It renders element names and attributes as an indented tree, preserves the context source label, applies the collapsed line budget independently to each tool result's top-level child lines and child count, and keeps raw text for malformed XML, mixed text, declarations, processing instructions, doctypes, and comments. A known tool's raw XML remains literal unless that tool declares its own result presenter. This XML fallback is TUI-only.
+
+## Alternatives considered
+
+**Strip XML-like tags with regular expressions.** Rejected because nested elements, attributes, entities, and malformed input require a real parser; partial conversion would make ambiguous output harder to inspect.
+
+**Parse every generic result.** Rejected because known tools own their presentation contract, and silently reinterpreting their literal XML would override that decision.
+
+**Show only raw XML.** Rejected because wrappers optimized for model consumption add terminal noise, particularly for filesystem reads and deeply nested structured results.
+
+## Consequences
+
+Filesystem reads are shorter in TUI cards without changing canonical model-facing content. Complete XML context messages, including workspace instruction reminders, become readable trees; unknown complete XML results become navigable trees and retain per-child context when collapsed. The TUI adds a strict SAX parser dependency and deliberately declines XML features (undefined entities, DOCTYPE, comments, processing instructions) that could hide or transform input beyond the conservative tree view. Predefined entities and character references do expand, so parsed text and attribute values are re-escaped for terminal output after parsing: a character reference can produce a control character that escaping the raw source never saw. Other UIs show raw generic content.

.agents/notes/implemented/feature/2026-07-24-readable-xml-tool-output.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: 可读的 XML 工具输出
+
+Status: implemented
+
+[English](2026-07-24-readable-xml-tool-output.md) | 中文
+
+## 问题
+
+面向模型的上下文和工具结果文本可能呈现面向传输的 XML 包装，而不是人们真正需要的信息。上下文生产方不声明呈现意图，而对于回放时拿不到工具定义的调用，仍需要一个保守的回退方案，并且该方案不得重新解释普通文字或不完整的标记。
+
+## 决策
+
+read 工具声明一个通用的完成结果呈现：去除自身的 `<path>`、`<type>` 和 `<content>` 包装，同时保留带行号的内容和尾部信息。这一由工具自身持有的投影一致地作用于所有消费工具呈现意图的 UI。
+
+只有当完整文本恰为一个受支持的 XML 文档时，TUI 才把上下文消息或工具定义不可用的工具结果按 XML 解析。TUI 将元素名和属性渲染为缩进树，保留上下文的来源标签；对于每个工具结果，分别按折叠行数预算限制各顶层子元素的行数和顶层子元素数量；对于格式错误的 XML、混合文本、XML 声明、处理指令、doctype 和注释，则保留原始文本。除非已知工具声明了自己的结果呈现器，否则其原始 XML 仍按字面显示。这一 XML 回退机制仅限 TUI。
+
+## 曾考虑的替代方案
+
+**用正则表达式剥除类 XML 标签。** 已否决：嵌套元素、属性、实体和格式错误的输入都需要真正的解析器；部分转换会让本就有歧义的输出更难检查。
+
+**解析所有通用结果。** 已否决：已知工具拥有自己的呈现契约，静默重新解释它们的字面 XML 会推翻这一决定。
+
+**只显示原始 XML。** 已否决：为模型消费而优化的包装会给终端增加噪音，对文件系统读取和嵌套很深的结构化结果尤其如此。
+
+## 后果
+
+文件系统读取在 TUI 卡片中变得更短，而规范的面向模型内容保持不变。完整的 XML 上下文消息（包括工作区指令提醒）变成可读的树；未知的完整 XML 结果变成可导航的树，折叠时也保留每个子元素的上下文。TUI 新增一个严格 SAX 解析器依赖，并有意不支持那些可能在保守树视图之外隐藏或变换输入的 XML 特性（未定义实体、DOCTYPE、注释、处理指令）。预定义实体和字符引用会被展开，因此解析出的文本和属性值在解析后会为终端输出重新转义：字符引用可能产生对原始源文本转义时从未见过的控制字符。其他 UI 展示原始的通用内容。

.agents/notes/implemented/feature/2026-07-24-tui-banner-model-deduplication.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 .agents/notes/implemented/feature/2026-07-24-tui-banner-model-deduplication.md
+2026-07-24-tui-banner-model-deduplication.md: afd370a8762d8e6c17c61d50c95d68998a063df5
+2026-07-24-tui-banner-model-deduplication.zh.md: 86a3cdb0e714642253162f1fe062e19bdc40bbe4

.agents/notes/implemented/feature/2026-07-24-tui-banner-model-deduplication.md

@@ -0,0 +1,33 @@
+# Agent Note: The startup banner omits the model
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-banner-model-deduplication.zh.md)
+
+## Problem
+
+The startup banner repeated the selected model directly above the prompt context, which already keeps the model visible while the TUI is idle. The duplicate added no information and made the banner detail line harder to scan.
+
+## Decision
+
+- The borderless startup banner shows the product title, optional `welcome` or session-title subtitle, and session id.
+- The banner omits the model name. The prompt context remains the persistent model display and updates after `/model` selection.
+- The sweep animation and configured-welcome behavior are unchanged.
+
+This supersedes only the model-in-banner portion of the [borderless banner decision](../../archived/feature/2026-07-21-tui-borderless-banner.md).
+
+## Alternatives considered
+
+**Remove the entire detail line.** Rejected: the session id remains useful for identifying and resuming the active session, and it is not duplicated in the prompt context.
+
+**Remove the model from the prompt context instead.** Rejected: the prompt context stays visible after the startup banner scrolls away and reflects later model selections.
+
+## Consequences
+
+- Startup uses the banner detail row only for the session id.
+- The model appears once in the initial idle view, in the prompt context.
+- Banner snapshots and runnable TUI replay snapshots contain a shorter detail row.
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` asserts that completed banners retain the session id without the former `<model>  •  <session-id>` text. Package-local and runnable-example TUI snapshots pin the resulting rows.

.agents/notes/implemented/feature/2026-07-24-tui-banner-model-deduplication.zh.md

@@ -0,0 +1,33 @@
+# Agent Note：启动横幅不再显示模型
+
+Status: implemented
+
+[English](2026-07-24-tui-banner-model-deduplication.md) | 中文
+
+## 问题
+
+启动横幅在提示区上下文（prompt context）的正上方重复显示所选模型，而提示区上下文本身已在 TUI 空闲时持续展示模型。这一重复不提供任何信息，还让横幅详情行更难扫读。
+
+## 决策
+
+- 无边框启动横幅显示产品标题、可选的 `welcome` 或会话标题副标题，以及会话 id。
+- 横幅不再显示模型名。提示区上下文仍是常驻的模型展示位，并在 `/model` 选择后随之更新。
+- 扫入动画和配置了欢迎语时的行为保持不变。
+
+本 note 仅取代[无边框横幅决策](../../archived/feature/2026-07-21-tui-borderless-banner.md)中模型进横幅的那部分。
+
+## 考虑过的替代方案
+
+**移除整条详情行。** 否决：会话 id 对识别和恢复当前会话仍然有用，而且它在提示区上下文中没有重复。
+
+**改为把模型从提示区上下文移除。** 否决：提示区上下文在启动横幅滚出视野后仍保持可见，并会反映之后的模型选择。
+
+## 后果
+
+- 启动时横幅详情行只承载会话 id。
+- 在初始空闲视图中模型只出现一次，位于提示区上下文。
+- 横幅快照和可运行的 TUI 回放快照包含更短的详情行。
+
+## 测试
+
+`packages/ui/tui/tests/tui.spec.ts` 断言完成后的横幅保留会话 id，且不含先前的 `<model>  •  <session-id>` 文本。包内快照与可运行示例的 TUI 快照固定了最终的各行内容。

.agents/notes/implemented/feature/2026-07-24-tui-message-header-timing.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-24-tui-message-header-timing.md: 94a4d04c75f9b0ad76e2460738a07ba82ac3bb9f
+2026-07-24-tui-message-header-timing.zh.md: 4713555290bbc47bb3af56cd3b4d0c493c81e6f1

.agents/notes/implemented/feature/2026-07-24-tui-message-header-timing.md

@@ -0,0 +1,25 @@
+# Agent Note: TUI message header timing
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-message-header-timing.zh.md)
+
+## Problem
+
+Turn timing beside the editor disappears from the transcript when the user scrolls and cannot appear until the editor status renders. A whole-turn aggregate also obscures the latency of later model requests after tool calls.
+
+## Decision
+
+Every model step creates an assistant header at `step/start`, before the first streamed chunk. The header displays `Model wait` immediately and refreshes at 100 ms resolution, then adds exclusive `Thinking`, `Response`, and `Tools` buckets as session events move the step between phases.
+
+`step/end` freezes the header and adds the local completion timestamp. Transcript replay derives the same timing from durable event timestamps. Empty and tool-only steps retain a header, while failed live output and its header retract together when retry handling rebuilds the active session surface.
+
+The prompt context retains only queued-steering state. Timing belongs to the model step that produced it rather than to the editor or the whole turn.
+
+## Alternatives considered
+
+Keeping timing beside the editor preserves a stable layout but hides per-step latency in scrollback and resume. Adding a second status line duplicates the same metric in two places. Labeling the first bucket `TTFT` is compact but requires protocol terminology; `Model wait` states the user-visible meaning without claiming that the first chunk is always text.
+
+## Consequences
+
+Users receive visible feedback before model output and can compare each request after tools or retries. Updating at 100 ms resolution causes more terminal renders while a model step is active. Internal timing state keeps the established `ttft` name because it identifies the measured bucket precisely; only rendered text uses `Model wait`.

.agents/notes/implemented/feature/2026-07-24-tui-message-header-timing.zh.md

@@ -0,0 +1,25 @@
+# Agent Note：TUI 消息头部计时
+
+Status: implemented
+
+[English](2026-07-24-tui-message-header-timing.md) | 中文
+
+## 问题
+
+编辑器旁的轮次计时会在用户滚动时从 transcript（文本记录）中消失，且要等到编辑器状态渲染后才能出现。整轮聚合值还会掩盖工具调用之后各后续模型请求的延迟。
+
+## 决策
+
+每个模型步骤都在 `step/start` 时（即第一个流式分片到达之前）创建一个 assistant 头部。头部立即显示 `Model wait` 并以 100 ms 分辨率刷新；随着会话事件使该步骤在不同阶段之间切换，头部再加入互斥的 `Thinking`、`Response` 和 `Tools` 时间桶。
+
+`step/end` 冻结头部并附上本地完成时间戳。transcript 回放从持久事件时间戳派生出相同的计时。空步骤和纯工具步骤同样保留头部；当重试处理重建活跃会话表层时，失败的实时输出与其头部一并撤除。
+
+提示区上下文（prompt context）只保留排队中的 steering（中途引导）状态。计时归属于产生它的模型步骤，而不是编辑器或整个轮次。
+
+## 考虑过的替代方案
+
+把计时留在编辑器旁能保持布局稳定，但在 scrollback 和会话恢复中看不到各步骤的延迟。增加第二条状态行会让同一指标出现在两处。把第一个时间桶标为 `TTFT` 更紧凑，但依赖协议术语；`Model wait` 直接陈述用户可见的含义，而不宣称第一个分片总是文本。
+
+## 后果
+
+用户在模型输出之前就能得到可见反馈，并能比较工具或重试之后的每次请求。以 100 ms 分辨率刷新会在模型步骤活跃期间带来更多终端渲染。内部计时状态沿用既有的 `ttft` 名称，因为它精确标识所计量的时间桶；只有渲染文本使用 `Model wait`。

.agents/notes/implemented/feature/2026-07-24-tui-prompt-status-indicator.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-24-tui-prompt-status-indicator.md: 8d469c3b0627325f373ca8f8d4d23d67bb09e342
+2026-07-24-tui-prompt-status-indicator.zh.md: 0dee8d1e4e7ce5a6f0299f9b7cd1595f63bd6e08

.agents/notes/implemented/feature/2026-07-24-tui-prompt-status-indicator.md

@@ -0,0 +1,33 @@
+# Agent Note: TUI prompt status indicator
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-prompt-status-indicator.zh.md)
+
+## Problem
+
+While a turn runs, the input prompt shows only its static `dsh>` prefix. The assistant header carries the elapsed timing, but the editor row — where the user's attention rests — gives no live signal of what the agent is doing right now: waiting for the first token, thinking, responding, or running tools.
+
+## Decision
+
+While the agent is running, a phase-specific glyph replaces the `>` caret of the built-in `${indicator}` prompt value. The `inputPrompt` theme template defaults to `${symbol} ${indicator}`, where the built-in `${symbol}` value holds the `dsh` label and `${indicator}` holds the caret slot with its trailing gap before the cursor; the template literal space separates them, rendering `dsh <glyph> ` in every state. The phase is the open step's active timing bucket, derived from the same session events and rules that drive the [message header timing](2026-07-24-tui-message-header-timing.md) — no new phase model. One glyph per bucket: `◍` model wait (pre-first-token), `✻` thinking, `●` responding, `⚙` tools. A running turn with no open step falls back to the model-wait glyph; an idle agent restores the plain `>`.
+
+The glyph occupies the caret's exact column with the same display width every frame, so the cursor never shifts as the phase changes or the glyph animates. Activity is conveyed by a brightness pulse, not by appearing and disappearing: a four-frame triangle wave (dim → normal → bold → normal) wraps the accent-colored glyph in the true SGR intensity codes (2 and 1) — never the palette's semantic `dim` role, which on a light scheme is a color the glyph's own accent would override — so the pulse survives every terminal scheme. The render-clock cadence is 250 ms per frame, a fixed presentation rhythm alongside the sibling 100 ms status refresh, not a deployment choice. The running-status timer refreshes every 100 ms tick unconditionally rather than only when a streaming component exists, so the pulse animates even during the pre-first-token wait.
+
+The caret and its animation are their own `${indicator}` value, separate from the `${symbol}` label, so the `inputPrompt` template composes the two: `${symbol} ${indicator}` reads as `dsh <caret>`. Configurability lives at that template — a deployment reorders or drops either value, and omitting `${indicator}` opts out of the running indicator. The glyph set, the pulse, and the `dsh` label are fixed in code — not per-deployment fields — matching the fixed timing-bucket labels they mirror.
+
+The built-in `${symbol}`/`${indicator}` updates ride the renders the TUI already drives on every state change that can move a value (`agent/status`, session events, the 100 ms running-status timer, async model-context resolution). A prompt value that changes on its own schedule — a plugin-owned `${custom}` fragment — instead redraws through the registry's coalesced change notification, which the renderer subscribes to directly rather than through a Cordis event ([registry](2026-07-24-configurable-tui-prompt-theme.md)).
+
+## Alternatives considered
+
+**Prepend the glyph before `dsh>` as its own `${status}` token.** Rejected: a leading token shifts the whole prompt — and the cursor — right by two columns whenever it appears, and collapses back when it clears. Replacing the caret keeps the cursor column fixed.
+
+**A blinking glyph that appears and disappears.** Rejected: on/off blanking still moves nothing horizontally once the glyph owns the caret column, but the empty frames read as flicker. A brightness pulse animates continuously while the character stays put.
+
+**A per-phase spinner animation** (rotating frames). Rejected: the four phases are already distinguished by their glyph shapes; swapping the character per frame would conflate "which phase" with "still working". The pulse animates intensity while the shape stays a stable phase signal, reusing the existing 100 ms status timer.
+
+**A new phase state machine in the TUI.** Rejected: the header-timing machinery already replays the open step's active bucket from session events. Deriving the glyph from that bucket keeps one source of truth for "what phase is this step in".
+
+## Consequences
+
+The user gets a live, glanceable phase signal in the caret they are already watching, with no horizontal movement of the cursor or the prompt. The pulse costs terminal renders on every 100 ms tick for the whole running turn, not only while a streaming component is mounted. The glyph mapping and the pulse are fixed in code, not configurable, matching the fixed timing-bucket labels they mirror.

.agents/notes/implemented/feature/2026-07-24-tui-prompt-status-indicator.zh.md

@@ -0,0 +1,33 @@
+# Agent Note：TUI 提示区状态指示器
+
+Status: implemented
+
+[English](2026-07-24-tui-prompt-status-indicator.md) | 中文
+
+## 问题
+
+轮次运行期间，输入提示区只显示其静态的 `dsh>` 前缀。assistant 头部承载已用计时，但编辑器所在的这一行——也就是用户注意力所在之处——对 agent 此刻正在做什么没有任何实时信号：是在等待第一个 token、思考、响应，还是在运行工具。
+
+## 决策
+
+agent 运行期间，一个按阶段区分的字形会替换内置 `${indicator}` 提示区值中的 `>` 光标符。`inputPrompt` 主题模板默认为 `${symbol} ${indicator}`，其中内置 `${symbol}` 值承载 `dsh` 标签，`${indicator}` 承载光标符槽位及其在光标前的尾随间隙；模板中的字面空格将两者隔开，在每种状态下渲染为 `dsh <字形> `。阶段取自当前打开步骤的活跃计时桶，其派生所依据的会话事件与规则和[消息头部计时](2026-07-24-tui-message-header-timing.md)相同——没有引入新的阶段模型。每个桶对应一个字形：`◍` 等待模型（第一个 token 之前）、`✻` 思考、`●` 响应、`⚙` 工具。运行中但没有打开步骤的轮次回退到等待模型的字形；agent 空闲时则恢复为纯 `>`。
+
+字形占据光标符所在的同一列，且每一帧的显示宽度都相同，因此无论阶段切换还是字形动画，光标都不会移动。活动状态由亮度脉动传达，而不是靠出现和消失：一个四帧三角波（暗 → 正常 → 亮 → 正常）用真正的 SGR 强度码（2 与 1）包裹带 accent 色的字形——绝不使用调色板语义上的 `dim` 角色，因为在浅色 scheme 下它是一种颜色，会被字形自身的 accent 色覆盖——因此脉动在任何终端 scheme 下都能保留。渲染时钟节拍为每帧 250 ms，是与配套的 100 ms 状态刷新并列的固定呈现节奏，而非部署选项。运行状态计时器每 100 ms 无条件刷新一次，而不再只在存在流式组件时刷新，因此即使在第一个 token 之前的等待期间，脉动也能持续。
+
+光标符及其动画自成一个 `${indicator}` 值，与 `${symbol}` 标签分离，因此 `inputPrompt` 模板将二者组合：`${symbol} ${indicator}` 读作 `dsh <光标符>`。可配置性位于该模板——部署可重排或丢弃任一值，省略 `${indicator}` 即退出运行指示器。字形集、脉动以及 `dsh` 标签都固定在代码中——不是逐部署字段——与它们映射的固定计时桶标签一致。
+
+内置 `${symbol}`/`${indicator}` 的更新搭乘 TUI 本就在每次可能改变某个值的状态变化（`agent/status`、会话事件、100 ms 运行状态计时器、异步模型上下文解析）时驱动的渲染。而一个自行变化的值——插件拥有的 `${custom}` 片段——则通过注册表的合并变更通知重绘，而渲染器直接订阅它，而非通过 Cordis 事件（参见[注册表](2026-07-24-configurable-tui-prompt-theme.md)）。
+
+## 考虑过的替代方案
+
+**把字形作为自己的 `${status}` token 前置在 `dsh>` 之前。** 已否决：前置 token 每次出现都会把整个提示区——连同光标——向右移动两列，清除时又缩回。在尾随的 `${indicator}` 槽位替换光标符能让光标列保持固定。
+
+**出现又消失的闪烁字形。** 已否决：一旦字形占据光标符所在列，开/关式的空白帧在水平方向上不再移动任何东西，但空帧读起来像闪烁。亮度脉动让字符保持不动的同时持续做动画。
+
+**按阶段的 spinner 动画**（旋转帧）。已否决：四个阶段已经通过各自的字形形状区分；逐帧切换字符会把「哪个阶段」与「仍在工作」混为一谈。脉动只改变强度做动画，而形状始终是稳定的阶段信号，且复用了既有的 100 ms 状态计时器。
+
+**在 TUI 中新建阶段状态机。** 已否决：头部计时机制已从会话事件回放出当前打开步骤的活跃桶。从该桶派生字形，能让「这个步骤处于哪个阶段」保持单一事实来源。
+
+## 后果
+
+用户在自己本就注视的光标符处获得可一眼掌握的实时阶段信号，且光标与提示区都没有水平移动。脉动的代价是整个运行轮次内每 100 ms 一次的终端渲染，而不再只在流式组件挂载期间。字形映射与脉动都固定在代码中、不可配置，与其所对应的固定计时桶标签一致。

.agents/notes/implemented/feature/2026-07-24-tui-prompt-workspace-label.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-24-tui-prompt-workspace-label.md: c45c60c6554766cca01076b229956a7bc7d98d48
+2026-07-24-tui-prompt-workspace-label.zh.md: 170dba83becf4b529679e7db9c7c84a6de7dec13

.agents/notes/implemented/feature/2026-07-24-tui-prompt-workspace-label.md

@@ -0,0 +1,34 @@
+# Agent Note: The prompt context combines directory and branch
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-prompt-workspace-label.zh.md)
+
+## Problem
+
+The idle prompt context rendered the working directory and `git:<branch>` as separate segments. In task worktrees, the directory can already identify the checkout, while the prefixed branch segment consumed additional horizontal space and was discarded independently on narrower terminals.
+
+## Decision
+
+- The prompt context renders the working directory and available Git branch as one workspace label: `<directory> (<branch>)`.
+- The directory remains bold and accented; the parenthesized branch remains muted.
+- The combined workspace label has the highest retention priority and is clipped as one segment when it exceeds the terminal width.
+- Outside a Git worktree or on detached HEAD, the label remains the directory alone.
+
+## Alternatives considered
+
+**Keep `git:<branch>` as a separate segment.** Rejected: the prefix and separator use more columns without adding meaning in this context.
+
+**Show only the branch.** Rejected: the session working directory determines where tools operate and remains the primary prompt context.
+
+**Derive a special worktree root label.** Rejected: the existing formatted directory and Git branch already provide the two relevant facts without adding repository-layout assumptions.
+
+## Consequences
+
+- A typical checkout renders as `~/git/tui-staging (tui-staging)`.
+- Narrow terminals retain or clip directory and branch together instead of dropping the branch independently.
+- Embedding-provided `TuiRuntime.formatCwd` labels compose with the branch in the same form.
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` pins home, absolute, formatted, and narrow workspace labels. Package-local and runnable-example TUI snapshots verify the assembled prompt context.

.agents/notes/implemented/feature/2026-07-24-tui-prompt-workspace-label.zh.md

@@ -0,0 +1,34 @@
+# Agent Note：提示区上下文合并显示目录与分支
+
+Status: implemented
+
+[English](2026-07-24-tui-prompt-workspace-label.md) | 中文
+
+## 问题
+
+空闲提示区上下文（prompt context）把工作目录和 `git:<branch>` 作为两个独立片段渲染。在任务 worktree 中，目录本身往往已能标识当前检出，而带前缀的分支片段额外占用横向空间，且在较窄的终端上会被单独丢弃。
+
+## 决策
+
+- 提示区上下文把工作目录和可用的 Git 分支渲染为一个工作区标签（workspace label）：`<directory> (<branch>)`。
+- 目录仍为加粗强调色；括号内的分支仍为弱化色。
+- 合并后的工作区标签具有最高保留优先级，超出终端宽度时作为一个整体片段裁剪。
+- 不在 Git worktree 中或处于 detached HEAD 时，标签仍只显示目录。
+
+## 考虑过的替代方案
+
+**保留 `git:<branch>` 作为独立片段。** 否决：前缀和分隔符占用更多列宽，在此上下文中却不增加信息。
+
+**只显示分支。** 否决：会话工作目录决定工具在哪里运行，仍是提示区上下文的首要信息。
+
+**派生一个特殊的 worktree 根目录标签。** 否决：现有的格式化目录和 Git 分支已经提供了这两项相关信息，无需引入对仓库布局的假设。
+
+## 后果
+
+- 典型的检出渲染为 `~/git/tui-staging (tui-staging)`。
+- 窄终端把目录和分支作为整体保留或裁剪，而不是单独丢弃分支。
+- 嵌入方通过 `TuiRuntime.formatCwd` 提供的标签以同样的形式与分支组合。
+
+## 测试
+
+`packages/ui/tui/tests/tui.spec.ts` 固定了主目录、绝对路径、格式化及窄终端下的工作区标签。包内快照与可运行示例的 TUI 快照验证了组装后的提示区上下文。

.agents/notes/implemented/feature/2026-07-24-tui-shell-prompt-editor.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-24-tui-shell-prompt-editor.md: bba03e788b92692f534fd97e66035757e9c74356
+2026-07-24-tui-shell-prompt-editor.zh.md: 1897d11292ec3b189245169956ac327f0b81b0e2

.agents/notes/implemented/feature/2026-07-24-tui-shell-prompt-editor.md

@@ -0,0 +1,33 @@
+# Agent Note: TUI shell-prompt editor
+
+Status: implemented
+
+English | [中文](2026-07-24-tui-shell-prompt-editor.zh.md)
+
+## Problem
+
+The upstream pi-tui editor always renders horizontal frame rows. That presentation separates input from the transcript but occupies two terminal rows and does not resemble the command-oriented input used by shells.
+
+## Decision
+
+The TUI presents a two-line prompt. A DSH-owned context line shows the working directory, running-turn timing, optional Git branch, current model, token totals, cache hit rate, and context pressure as independently prioritized segments. Narrow terminals omit lower-priority segments while retaining the directory, followed by running timing when it is present. The second line uses a fixed-width `dsh> ` prefix and equal-width continuation indent; its running steer/cancel guidance is placeholder text that disappears when input begins.
+
+The pinned `@earendil-works/pi-tui` package carries a pnpm patch that adds `frame: "none"` and fixed-width prompt prefixes to `EditorOptions`. The default remains the upstream horizontal frame, so only the DSH editor opts into the behavior. Prefixes must have equal visible widths; construction fails when they differ. Input, explicit newlines, autocomplete, cursor placement, and scroll indicators share the reduced first-row width; automatically wrapped rows render no prefix, so their text starts at the editor's left padding, occupies the prefix columns, and wraps at the full content width.
+
+The patch stays limited to the published editor JavaScript and declarations. Keeping the exact dependency pin makes installation either apply the known patch or fail rather than silently dropping the presentation.
+
+## Alternatives considered
+
+**Filter the rendered editor output in a wrapper.** This would depend on recognizing ANSI-styled border and scroll-indicator rows and distinguishing autocomplete output from input output, all of which are undocumented render details.
+
+**Vendor the complete pi-tui package.** The project updates frequently, while this change needs only a localized editor rendering option. Owning the full source and synchronization process would add disproportionate maintenance.
+
+**Keep the horizontal frame.** This avoids dependency customization but retains the presentation the change is intended to replace.
+
+## Consequences
+
+The editor and context use two rows instead of the framed editor plus footer, with one blank row separating the prompt area from conversation cards. The persistent presentation omits session identity and tool-card mode; `/status` and commands retain those details. Input layout and autocomplete lose six columns to the prompt prefix, but wrapped text uses the otherwise blank prefix columns. Borderless scrolling uses standalone `↑ N more` and `↓ N more` rows.
+
+The internal segment representation establishes width priorities without exposing a public customization language. Future Starship-like configuration can build on it after the default modules and overflow behavior have production evidence.
+
+A pi-tui upgrade requires reviewing and reapplying or retiring the patch. TUI terminal snapshots pin the assembled presentation, including context modules, prompt color, alignment, cursor placement, and autocomplete width.

.agents/notes/implemented/feature/2026-07-24-tui-shell-prompt-editor.zh.md

@@ -0,0 +1,33 @@
+# Agent Note: TUI shell 提示符编辑器
+
+Status: implemented
+
+[English](2026-07-24-tui-shell-prompt-editor.md) | 中文
+
+## 问题
+
+上游 pi-tui 编辑器始终渲染横向边框行。这种呈现方式虽然把输入区与 transcript（文本记录）分隔开，却占用两行终端高度，也不像 shell 中面向命令的输入形态。
+
+## 决策
+
+TUI 呈现两行提示符。DSH 自有的上下文行把工作目录、运行中轮次的计时、可选的 Git 分支、当前模型、token 总量、缓存命中率与上下文压力显示为各自独立分配优先级的段（segment）。窄终端会省略低优先级的段，但保留目录；运行中计时存在时，其保留优先级仅次于目录。第二行使用固定宽度的 `dsh> ` 前缀与等宽的续行缩进；agent 运行期间提示 steering（中途引导）与取消的引导文字是占位文本，开始输入后即消失。
+
+固定版本的 `@earendil-works/pi-tui` 包（package）携带一个 pnpm 补丁，为 `EditorOptions` 增加 `frame: "none"` 与固定宽度的提示符前缀。默认值仍是上游的横向边框，因此只有 DSH 编辑器选择启用该行为。两个前缀的可见宽度必须相等；宽度不同时构造会失败。输入、显式换行、自动补全、光标定位和滚动指示共用缩减后的首行宽度；自动折行产生的行不渲染前缀，其文本从编辑器左侧留白处开始，占用前缀列，并按完整内容宽度折行。
+
+补丁范围仅限已发布的编辑器 JavaScript 与类型声明。依赖保持精确的版本固定，使安装要么应用已知补丁，要么直接失败，而不会静默丢掉这种呈现方式。
+
+## 曾考虑的替代方案
+
+**在包装层过滤编辑器的渲染输出。** 这需要识别带 ANSI 样式的边框行与滚动指示行，并区分自动补全输出与输入输出，而这些都是未见于文档的渲染细节。
+
+**vendor 完整的 pi-tui 包。** 该项目更新频繁，而本次改动只需要一个局部的编辑器渲染选项。接手全部源码及其同步流程会带来不成比例的维护成本。
+
+**保留横向边框。** 这可以避免定制依赖，但保留的正是本次改动想要替换的呈现方式。
+
+## 后果
+
+编辑器与上下文共占两行，取代原先带边框的编辑器加页脚，提示符区域与对话卡片之间以一行空行分隔。常驻呈现不含会话标识与工具卡片模式；`/status` 与各命令仍保留这些细节。输入布局与自动补全因提示符前缀占位而损失六列宽度，但折行后的文本会占用原本留空的前缀列。无边框滚动使用独立的 `↑ N more` 与 `↓ N more` 行。
+
+段的内部表示确立了宽度优先级，而未暴露公开的定制语言。待默认模块与溢出行为积累生产环境证据后，未来可在其上构建类似 Starship 的配置。
+
+升级 pi-tui 时需要评审该补丁，并重新应用或将其退役。TUI 终端快照固定组装后的呈现效果，包括上下文模块、提示符颜色、对齐、光标定位和自动补全宽度。

.agents/notes/implemented/feature/2026-07-27-assistant-timing-header-trailing.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 .agents/notes/implemented/feature/2026-07-27-assistant-timing-header-trailing.md
+2026-07-27-assistant-timing-header-trailing.md: a315a0620c63f25660220e55cf5187d7117c14d1
+2026-07-27-assistant-timing-header-trailing.zh.md: 84b8612337a345912371e37952195e4602f7ca25

.agents/notes/implemented/feature/2026-07-27-assistant-timing-header-trailing.md

@@ -0,0 +1,25 @@
+# Agent Note: Assistant timing line renders after the message body
+
+Status: implemented
+
+English | [中文](2026-07-27-assistant-timing-header-trailing.zh.md)
+
+## Problem
+
+The TUI assistant message opened with a single header line joining the `Assistant` label and the step-timing string (`Assistant · Model wait 0.0s · Completed …`). Placing the timing before the body pushed the durations away from the answer they describe and, once completed, buried the reply's first line under a metadata line the reader scans past.
+
+## Decision
+
+**Split the label from the timing; render the timing as the message's trailing line.**
+
+`AssistantMessageComponent` (packages/ui/tui/src/index.ts) now emits the bold `Assistant` label as the first line and appends the dim timing string (already assembled by `StreamingAssistantComponent.rebuild()` as `header`, including the `· Completed …` suffix when settled) as the last child, after reasoning and text. The timing content, bucket-hiding, and completion-time behavior are unchanged — only its position moved from the top to the bottom of the message.
+
+## Alternatives considered
+
+**Move the whole header line (label included) to the end.** Rejected: the `Assistant` label orients the reader to who is speaking and belongs at the top like the `You` label; only the timing metadata benefits from trailing placement.
+
+**Keep the timing inline but below the label as a second top line.** Rejected: that still separates the durations from the completed answer and keeps two metadata lines between the prompt and the reply.
+
+## Consequences
+
+Each assistant message reads label → reasoning → answer → timing, so completed timing sits next to the reply it measures. The keyless TUI snapshot suite was refreshed to pin the new layout across every fixture; four `tui.spec.ts` assertions that matched the old inline `Assistant · Model wait …` string now assert the label and timing separately, since the two no longer render contiguously.

.agents/notes/implemented/feature/2026-07-27-assistant-timing-header-trailing.zh.md

@@ -0,0 +1,25 @@
+# Agent Note: Assistant timing line renders after the message body
+
+Status: implemented
+
+[English](2026-07-27-assistant-timing-header-trailing.md) | 中文
+
+## Problem
+
+TUI 的助手消息此前以一行开头，把 `Assistant` 标签和步骤计时串拼在一起（`Assistant · Model wait 0.0s · Completed …`）。计时放在正文之前，使耗时数据远离它所描述的回答；一旦完成，回复的首行还被读者会略过的元数据行压在下面。
+
+## Decision
+
+**把标签与计时拆开；计时作为消息的末行渲染。**
+
+`AssistantMessageComponent`（packages/ui/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
+
+## Alternatives considered
+
+**把整行表头（含标签）都移到末尾。** 否决：`Assistant` 标签让读者知道是谁在说话，应与 `You` 标签一样置顶；只有计时这类元数据才受益于置底。
+
+**计时仍内联，但作为标签下方的第二行置顶。** 否决：这仍把耗时数据与完成的回答分离，并在提示与回复之间保留两行元数据。
+
+## Consequences
+
+每条助手消息按 标签 → reasoning → 回答 → 计时 阅读，完成计时紧挨它所度量的回复。无密钥的 TUI 快照套件已刷新，在每个 fixture 中固定新布局；`tui.spec.ts` 中四处原先匹配旧内联串 `Assistant · Model wait …` 的断言，现改为分别断言标签与计时，因为两者不再连续渲染。

.agents/notes/implemented/feature/2026-07-27-tui-running-glyph-smooth-fade.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 .agents/notes/implemented/feature/2026-07-27-tui-running-glyph-smooth-fade.md
+2026-07-27-tui-running-glyph-smooth-fade.md: e4c8fee399c2269bfe53976d3358bc643b2daf6a
+2026-07-27-tui-running-glyph-smooth-fade.zh.md: 25bda3d549b1a7548e997f8801858d1efa32e3eb

.agents/notes/implemented/feature/2026-07-27-tui-running-glyph-smooth-fade.md

@@ -0,0 +1,37 @@
+# Agent Note: Dim-gray pulse for the running prompt glyph
+
+Status: implemented
+
+English | [中文](2026-07-27-tui-running-glyph-smooth-fade.zh.md)
+
+## Problem
+
+While a turn runs, the TUI replaces the `>` prompt caret with a phase glyph (`◍`/`✻`/`●`/`⚙`). Earlier iterations animated its brightness in the accent blue (a discrete SGR wave, then a truecolor throb) — a colored, always-pulsing indicator. The desired effect keeps the continuous pulse to signal ongoing work, but as a quiet dim gray rather than a color, and with smooth fade-in and fade-out at its edges.
+
+## Decision
+
+The running glyph is a dim gray that fades in on turn start, throbs continuously while the turn runs, and fades out after it ends before the plain `>` caret returns. It is never the accent color.
+
+Brightness is a fade envelope times a running throb. The envelope gates appear/disappear, linear in the render clock over `STATUS_FADE_MS = 300`: `(now − startedAt)/FADE` clamped for fade-in, `1 − (now − endedAt)/FADE` for fade-out. `pulseLevel` is a cosine between `STATUS_PULSE_FLOOR` (0) and 1 over `STATUS_PULSE_PERIOD_MS = 1400`, so each breath swells from fully invisible to full and back. The truecolor opacity handed to `fadeGlyph` is `envelope × pulse`.
+
+`fadeGlyph` renders at that opacity. With truecolor, below `STATUS_FADE_MIN_OPACITY` (0.12) the glyph is hidden entirely — a blank column — so the pulse trough disappears rather than lingering as a near-background gray; above it the glyph interpolates a 24-bit gray between `STATUS_FADE_GRAY.trough` and `.settled` (the same dim gray as the idle caret), emitting `\x1b[38;2;r;g;bm`, so both the fade and the throb are brightness. Without truecolor there is no per-frame gray, so a separate `visible` flag — driven by the envelope alone, not the pulsing opacity — shows the glyph in the palette's muted role or leaves a blank column; the throb never blinks the fallback. With color off entirely a visible glyph is bare, preserving the caret column on a monochrome terminal.
+
+The running prompt refreshes at `STATUS_ANIMATION_INTERVAL_MS = 50` (~20 fps) so the throb moves every frame; the same tick keeps the 0.1 s-resolution elapsed text current, so no separate timing timer exists.
+
+Fade-out outlives the turn: on the running → non-running edge `beginFadeOut` hands the last rendered glyph to a `FadingStatus` whose own timer re-renders until the fade window elapses, then calls `clearStatus` and restores `>`. Teardown paths (dispose, agent-disposed, startup-failure) call `clearStatus` directly, stopping both the running and fading timers at once — no lingering fade. The glyph handed to the fade-out is the last live phase glyph (`runningStatus.lastGlyph`), not the ttft fallback the phase derivation returns once the closing turn's step has ended.
+
+The glyph character and its cell never change — only the gray brightness — so the caret column stays fixed across frames and across the caret↔glyph transitions.
+
+## Alternatives considered
+
+**Keep the accent color.** The pulse is wanted, but as a quiet gray matching the idle caret's tone, not a colored indicator; the accent is removed while the throb stays.
+
+**Hold steady while running (no throb).** A steady dim glyph was tried and rejected: a continuous pulse better conveys that the agent is actively working. The throb returns, in gray.
+
+**A non-zero floor that keeps the trough faintly visible.** Successive floors (0.45 → 0.15 → 0.02) each kept the dimmest point too visible to read as truly quiet; even 0.02 sat at gray ≈ 45, one step off the background. A floor of 0 with an explicit visibility threshold (`STATUS_FADE_MIN_OPACITY`) instead hides the glyph entirely at the bottom of each breath, so the trough is genuinely absent. Because the swell is a smooth cosine, the disappearance reads as a soft fade-out, not the hard on/off blink a low-but-nonzero gray toggle would give.
+
+**Pulse the non-truecolor fallback too.** SGR exposes only three intensity levels, too coarse for a smooth throb, and toggling the glyph on/off across the pulse would blink it. The fallback instead shows a steady muted glyph gated by the envelope; only truecolor terminals get the throb.
+
+## Consequences
+
+The running glyph reads as a quiet gray breath that swells from nothing to a dim mark and back the whole turn, matching the idle caret's tone, at the cost of a faster render tick (50 ms) while a turn is active or fading out; the diffing terminal only re-emits changed cells, so the extra frames are cheap. The fade-out means the indicator lingers ~300 ms after a turn completes. Snapshots run non-truecolor with a frozen clock, so they pin only the steady muted glyph (envelope-gated), not the throb; the truecolor invisible trough, the settled peak, a rising mid-frame, the fade-out, and the non-truecolor appear/disappear are pinned by unit tests in `tui.spec.ts`.

.agents/notes/implemented/feature/2026-07-27-tui-running-glyph-smooth-fade.zh.md

@@ -0,0 +1,37 @@
+# Agent Note: Dim-gray pulse for the running prompt glyph
+
+Status: implemented
+
+[English](2026-07-27-tui-running-glyph-smooth-fade.md) | 中文
+
+## Problem
+
+回合运行时，TUI 会把 `>` 提示符替换为阶段字形（`◍`/`✻`/`●`/`⚙`）。此前的迭代用强调蓝为其亮度做动画（先是离散 SGR 波，后是 truecolor 呼吸）——一个持续脉动的彩色指示器。期望的效果保留持续脉动以示正在工作，但改为安静的暗灰而非颜色，并在两端做平滑的淡入淡出。
+
+## Decision
+
+运行字形是一种暗灰色，在回合开始时淡入，运行期间持续脉动，回合结束后淡出，随后恢复为普通的 `>` 光标。它从不使用强调色。
+
+亮度是淡入淡出包络乘以运行脉冲。包络控制出现/消失，随渲染时钟在 `STATUS_FADE_MS = 300` 内线性变化：淡入为 `(now − startedAt)/FADE` 并做钳制，淡出为 `1 − (now − endedAt)/FADE`。`pulseLevel` 是在 `STATUS_PULSE_FLOOR`（0）与 1 之间、周期为 `STATUS_PULSE_PERIOD_MS = 1400` 的余弦，因此每次呼吸都从完全不可见涨到满亮再回落。交给 `fadeGlyph` 的 truecolor 不透明度为 `envelope × pulse`。
+
+`fadeGlyph` 以该不透明度渲染。在 truecolor 下，低于 `STATUS_FADE_MIN_OPACITY`（0.12）时字形被完全隐藏——留出空白列——因此脉冲谷值消失，而非停留为接近背景的灰；在其之上，字形在 `STATUS_FADE_GRAY.trough` 与 `.settled`（与空闲光标相同的暗灰）之间插值出 24 位灰色，发出 `\x1b[38;2;r;g;bm`，因此淡入与脉冲都表现为亮度。没有 truecolor 时不存在逐帧灰度，因此用一个单独的 `visible` 标志——只由包络驱动，而非脉动的不透明度——以调色板 muted 角色显示字形或留出空白列；脉冲从不使回退闪烁。完全关闭颜色时，可见字形以裸字符呈现，在单色终端上保住光标列。
+
+运行提示符以 `STATUS_ANIMATION_INTERVAL_MS = 50`（约 20 fps）刷新，使脉动逐帧移动；同一次 tick 也让 0.1 s 精度的耗时文本保持最新，因此不需要单独的计时器。
+
+淡出会延续到回合之后：在运行 → 非运行的边沿，`beginFadeOut` 把最后渲染的字形交给一个 `FadingStatus`，其自有计时器持续重绘，直到渐变窗口结束，然后调用 `clearStatus` 并恢复 `>`。拆解路径（dispose、agent-disposed、启动失败）直接调用 `clearStatus`，一次性停止运行与淡出两个计时器——不会有残留的渐变。交给淡出的字形是最后一次的实时阶段字形（`runningStatus.lastGlyph`），而非收尾回合的步骤结束后阶段推导返回的 ttft 兜底字形。
+
+字形字符及其单元格从不改变——只有灰色亮度变化——所以光标列在各帧之间以及光标↔字形的切换之间都保持固定。
+
+## Alternatives considered
+
+**保留强调色。** 需要脉冲，但要用与空闲光标一致的安静灰色，而非彩色指示器；移除强调色，保留脉动。
+
+**运行时保持稳定（不脉动）。** 曾试过稳定的暗色字形并被否决：持续脉动更能表明代理正在积极工作。脉动以灰色回归。
+
+**用非零下限让谷值保持微弱可见。** 逐次下限（0.45 → 0.15 → 0.02）都让最暗点太可见，读不出真正的安静；即便 0.02 也停在灰度约 45，仅比背景高一档。改用下限 0 加显式可见阈值（`STATUS_FADE_MIN_OPACITY`），在每次呼吸的底部完全隐藏字形，使谷值真正缺席。由于涨落是平滑余弦，消失读作柔和的淡出，而非低而非零的灰度开关会带来的硬性开/关闪烁。
+
+**让非 truecolor 回退也脉动。** SGR 只暴露三个强度档位，做平滑脉动太粗糙，而按脉冲开关字形会使其闪烁。回退改为由包络控制的稳定 muted 字形；只有 truecolor 终端获得脉动。
+
+## Consequences
+
+代价是运行或淡出期间渲染 tick 更快（50 ms），换来的是运行字形整段回合读作一种从无涨到暗记号再回落的安静灰色呼吸，与空闲光标的色调一致；差分终端只重发变化的单元格，因此额外帧开销很低。淡出意味着指示器在回合结束后残留约 300 ms。快照以非 truecolor、冻结时钟运行，因此只钉住由包络控制的稳定 muted 字形，而非脉动；truecolor 的不可见谷值、稳定峰值、上升中间帧、淡出、以及非 truecolor 的出现/消失均由 `tui.spec.ts` 的单元测试钉住。

.agents/notes/implemented/feature/2026-07-27-tui-tool-card-header.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 .agents/notes/implemented/feature/2026-07-27-tui-tool-card-header.md
+2026-07-27-tui-tool-card-header.md: 0868d8dcaf5ab1641a122ecda05578aef46f5f94
+2026-07-27-tui-tool-card-header.zh.md: 71db5fc6fc853039ea9be1cb1c51686f941c4cb7

.agents/notes/implemented/feature/2026-07-27-tui-tool-card-header.md

@@ -0,0 +1,35 @@
+# Agent Note: Fixed `Tool / <name>` header for tool-call cards
+
+Status: implemented
+
+English | [中文](2026-07-27-tui-tool-card-header.zh.md)
+
+## Problem
+
+The TUI rendered each tool call as `{glyph} {title}`, where `title` was the presenter's fused verb-plus-detail string (`Read src/index.ts (1200-1360)`, `Edit files`, or a bash card's model description), bold and underlined in the status color. One flat slot carried the tool identity, the target, and the status at once, and the styling mixed bold, underline, and color inconsistently — the header read as noise, and which tool ran was not visually separable from what it operated on.
+
+## Decision
+
+The header is a fixed `{ring} Tool / <name>` frame in a single flat status color — no bold, no underline, no dim — so one color reads consistently across the whole row. `Tool` is a literal constant; `<name>` is the raw tool name. The separator is ASCII `/`. The ring marker is `○` while the call is pending and `●` once it settles; the header color (warning pending / success ok / error) distinguishes pending from ok from error, so the same filled ring serves both settled states.
+
+The header carries exactly one optional extra: a bash (terminal) card's model-authored description, appended as a ` / <desc>` segment (`● Tool / bash / Run the coverage gate`). No other tool contributes a header detail.
+
+Every tool-specific detail moves into the body block below the header. A non-terminal card's presenter title (`Read src/index.ts`, `Grep pattern`) becomes the first body line, unless it only repeats the tool name (the fallback presenter for a tool with no `presentCall`, or an unknown tool), which the header already shows. A terminal card keeps its command as the `$`-line. A diff card drops its title entirely — the per-file path headers and a change footer carry the meaning — and appends a dim `└ +A -R · N file(s)` footer summarizing added/removed line counts across the files.
+
+The redesign is TUI-only. It touches `ToolCardComponent` in `packages/ui/tui/src/components/transcript.ts` and no presenter: the `Tool / <name>` frame derives the name TUI-side from the call's tool name, and the body-title relocation reuses the presenter title already returned. `presentation.ts` and every `presentCall`/`presentResult` are unchanged.
+
+## Alternatives considered
+
+**Bold the name to make it stand out.** Rejected: on terminals that render SGR-1 as the bright color variant, a bold green name reads as a different color from the rest of the green header — reintroducing the inconsistency the redesign removes. The name stands out by position in the fixed frame, not by weight.
+
+**Keep the presenter title in the header** (e.g. `Tool / read / Read src/index.ts`). Rejected: the verb duplicates the tool name, and non-bash tools have no genuinely distinct one-line description — the target belongs in the body, so only bash contributes a header desc.
+
+**A summary footer for every card type** (line counts, exit pills, diff counts as a uniform `└ …` line). Deferred: only the diff footer shipped. Terminal exit keeps its existing dim `[exit N]` line, long output keeps its existing head+tail middle-elision, an empty result stays header-only, and an error body stays plain (only the header color carries the error) — the current treatments were kept deliberately, not by omission.
+
+## Consequences
+
+A tool call now shows its identity in one stable place, and status reads as one flat color per row, so a transcript of many calls scans as a column of `Tool / <name>` rather than a wall of mixed-styled verb strings. The cost is one extra body line for non-terminal tools (the relocated title) and the loss of the earlier redundancy-suppression that omitted a diff's per-file path when the header already named it — the header no longer names any path, so every diff prints its path once. Because the change is confined to `ToolCardComponent`, other UI bridges (ACP, JSON-RPC) keep their own tool-call presentation; the `Tool / <name>` shape is TUI-local and not part of any cross-package contract.
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` pins the new header (`Tool / <name>`), the dropped diff title, the relocated generic title, and the `· N file(s)` footer. The keyless terminal snapshots under `packages/ui/tui/tests/snapshots/` and `examples/tui-agent/tests/snapshots/` — rendered through the real assembled TUI and a pseudo-terminal — were re-recorded and show the new cards for read, bash (described and undescribed), edit, and the other tools.

.agents/notes/implemented/feature/2026-07-27-tui-tool-card-header.zh.md

@@ -0,0 +1,35 @@
+# Agent Note: Fixed `Tool / <name>` header for tool-call cards
+
+Status: implemented
+
+[English](2026-07-27-tui-tool-card-header.md) | 中文
+
+## Problem
+
+TUI 曾把每次工具调用渲染为 `{glyph} {title}`，其中 `title` 是 presenter 拼接的「动词加细节」字符串（`Read src/index.ts (1200-1360)`、`Edit files`，或 bash 卡片的模型描述），以状态色加粗并加下划线显示。单一扁平的槽位同时承载了工具身份、操作对象和状态，而样式又混用了加粗、下划线和颜色，前后不一致——表头读起来像噪声，「运行了哪个工具」在视觉上与「它操作了什么」无法区分。
+
+## Decision
+
+表头是固定的 `{ring} Tool / <name>` 框架，采用单一扁平的状态色——不加粗、不加下划线、不变暗——因此整行的颜色保持一致。`Tool` 是字面常量；`<name>` 是原始工具名。分隔符是 ASCII 的 `/`。环形标记在调用挂起时为 `○`，落定后为 `●`；表头颜色（挂起用 warning、成功用 success、错误用 error）区分挂起、成功与错误，因此同一个实心环可同时服务于两种落定状态。
+
+表头只携带一个可选的额外内容：bash（终端）卡片由模型撰写的描述，作为 ` / <desc>` 段追加（`● Tool / bash / Run the coverage gate`）。其他工具都不向表头贡献细节。
+
+每一项工具专属的细节都移入表头下方的正文块。非终端卡片的 presenter 标题（`Read src/index.ts`、`Grep pattern`）成为正文第一行，除非它只是重复工具名（无 `presentCall` 的工具的兜底 presenter，或未知工具），此时表头已经显示过。终端卡片保留其命令作为 `$` 行。diff 卡片完全弃用其标题——由各文件的路径表头与一条变更页脚承载含义——并追加一条变暗的 `└ +A -R · N file(s)` 页脚，汇总各文件增删的行数。
+
+本次改版仅限 TUI。它改动 `packages/ui/tui/src/components/transcript.ts` 中的 `ToolCardComponent`，不触碰任何 presenter：`Tool / <name>` 框架在 TUI 侧从调用的工具名推导出名称，正文标题的迁移则复用 presenter 已返回的标题。`presentation.ts` 以及每一个 `presentCall`/`presentResult` 均保持不变。
+
+## Alternatives considered
+
+**把工具名加粗使其突出。** 已否决：在把 SGR-1 渲染为亮色变体的终端上，加粗的绿色工具名读起来与其余绿色表头是不同的颜色——重新引入了改版本要消除的不一致。工具名靠它在固定框架中的位置突出，而非靠字重。
+
+**把 presenter 标题保留在表头**（例如 `Tool / read / Read src/index.ts`）。已否决：动词与工具名重复，而非 bash 工具并没有真正独立的单行描述——操作对象属于正文，因此只有 bash 向表头贡献描述段。
+
+**为每一种卡片都加一条汇总页脚**（行数、退出码徽章、diff 计数统一为一条 `└ …` 行）。已推迟：仅 diff 页脚落地。终端退出保留其既有的变暗 `[exit N]` 行，长输出保留其既有的首尾中段省略，空结果保持仅表头，错误正文保持朴素（仅表头颜色承载错误）——这些既有处理是有意保留的，而非遗漏。
+
+## Consequences
+
+工具调用现在把身份显示在一个稳定的位置，状态每行读作一种扁平色，于是许多调用的记录扫读起来是一列 `Tool / <name>`，而非一堵混合样式的动词字符串之墙。代价是非终端工具多出一行正文（迁移过来的标题），以及丢失了先前的冗余抑制——当表头已命名路径时省略 diff 的各文件路径；如今表头不再命名任何路径，因此每个 diff 都会把路径打印一次。由于改动局限于 `ToolCardComponent`，其他 UI 桥（ACP、JSON-RPC）保留各自的工具调用呈现；`Tool / <name>` 的形态是 TUI 局部的，不属于任何跨包契约。
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` 固定了新表头（`Tool / <name>`）、弃用的 diff 标题、迁移后的 generic 标题以及 `· N file(s)` 页脚。`packages/ui/tui/tests/snapshots/` 与 `examples/tui-agent/tests/snapshots/` 下的无密钥终端快照——经由真实组装的 TUI 与伪终端渲染——已重新录制，展示了 read、bash（有描述与无描述）、edit 及其他工具的新卡片。

.agents/notes/implemented/simplification/2026-07-27-copyable-transcript-no-gutter-bar.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 .agents/notes/implemented/simplification/2026-07-27-copyable-transcript-no-gutter-bar.md
+2026-07-27-copyable-transcript-no-gutter-bar.md: 659b7d2f2f85bf7efe6b1006a2c61a14f3044560
+2026-07-27-copyable-transcript-no-gutter-bar.zh.md: 5c43169ba352ef1fef73ecf2188a32304aba9c26

.agents/notes/implemented/simplification/2026-07-27-copyable-transcript-no-gutter-bar.md

@@ -0,0 +1,34 @@
+# Agent Note: Copyable TUI transcript without gutter bars
+
+Status: implemented
+
+English | [中文](2026-07-27-copyable-transcript-no-gutter-bar.zh.md)
+
+## Problem
+
+The TUI grouped user prompts and tool cards behind a colored left-gutter bar (`▌ `) prepended to every body line, and indented assistant and system blocks by one column. Both are per-line prefixes: a terminal mouse drag-select over the scrollback captures the leading `▌ ` or the leading space on each line, so copy-paste of a message, a tool's output, or a code block pulls in decoration the user must strip by hand. The bar was the transcript's only per-message separator, so it could not simply be dropped without another way to tell messages apart.
+
+## Decision
+
+The scrollback carries no per-line prefix. Messages are separated only by a bold, underlined role header in the role color and blank-line spacing, both of which the terminal already inserts around each block. The underline gives each role a distinct visual band without a background fill, so it reads on any terminal theme and never enters the clipboard:
+
+- User and steering prompts (`UserMessageComponent`) are a plain `Container`: a bold, underlined accent `You` / `Steering` header line (via the shared `messageHeader` helper), then the prompt body at column 0.
+- Assistant blocks render a bold, underlined `Assistant` header, then reasoning and text at column 0, with the timing line at the end of the block (the former `paddingX = 1` indent is gone).
+- Tool cards drop the `GutterBox` wrapper. The card status (pending / error / success) colors the whole title line — the status glyph (`◌` / `✕` / `✓`) plus the title text share one color, bold and underlined to match the role headers — instead of a colored bar beside an uncolored title. The body renders unprefixed; body lines still pass through `Text` at the terminal width so overlong raw tool output wraps rather than overflowing.
+- The `GutterBox` class is deleted; nothing else used it.
+
+A drag-select over any of these regions now copies exactly the message text.
+
+## Alternatives considered
+
+- **Keep the bar only on user messages, drop it on tool cards** — leaves tool output, the most-copied region, still polluted. Rejected: the goal is a wholly copyable transcript.
+- **A single top rule or bar on the header line only** — the body copies clean, but selecting the header still captures a glyph, and it reintroduces a decoration character for no distinguishing gain over the underlined role header.
+- **Indent grouped bodies instead of a bar** — leading spaces still enter the clipboard, so it does not solve the copy problem; explicitly ruled out.
+- **A filled background band on the header** (reverse video, or a 256-color muted background) — gives each role a strong color block, but the saturated ANSI fill reads as too heavy and the 256-color shades are fixed rather than theme-remapped. The underline gives per-role distinction with a far lighter footprint.
+
+## Consequences
+
+- Copy-paste from the scrollback is clean with no user post-processing. This was the motivating win.
+- The transcript is flatter than the gutter-bar layout, but each role's bold, underlined header in the role color plus blank-line spacing keeps message boundaries clear without any left-edge fill. Tool-card status stays legible through the colored, underlined glyph and title.
+- Box-drawing borders (`│`) on transient overlays — status panel, model selector, resume list — are untouched. They are not scrollback message content and are rarely copied.
+- The affected keyless TUI `*.expected.txt` snapshots were re-recorded by fixture replay (no API key needed; the recorded LLM sessions are unchanged, only the render differs). Interactive boot and a round-trip prompt were verified in tmux.

.agents/notes/implemented/simplification/2026-07-27-copyable-transcript-no-gutter-bar.zh.md

@@ -0,0 +1,34 @@
+# Agent Note: 无 gutter bar 的可复制 TUI transcript
+
+Status: implemented
+
+[English](2026-07-27-copyable-transcript-no-gutter-bar.md) | 中文
+
+## Problem
+
+TUI 此前把用户提示词和工具卡片分组在一条彩色左侧 gutter bar（`▌ `）之后，该竖条被逐行加在每一行正文前面，并把 assistant 与系统块整体缩进一列。两者都是逐行前缀：在 transcript 上用鼠标框选时，每一行开头的 `▌ ` 或前导空格都会被一并选中，因此复制一条消息、一段工具输出或一个代码块时都会带上装饰字符，用户必须手动清理。该竖条又是 transcript 中唯一的逐条消息分隔标记，所以不能在没有其他区分方式的情况下直接删掉。
+
+## Decision
+
+transcript 不再带任何逐行前缀。消息仅通过以角色色渲染的粗体带下划线角色标题和空行分隔，而这两者本就由终端在每个块前后自动插入。下划线让每个角色获得清晰的视觉分带，且无需背景填充，因此在任何终端配色下都可读，也绝不会进入剪贴板：
+
+- 用户提示词与 steering 提示词（`UserMessageComponent`）改为普通 `Container`：一行粗体带下划线的强调色 `You` / `Steering` 标题（经共享的 `messageHeader` 辅助函数生成），随后是位于第 0 列的提示词正文。
+- Assistant 块渲染一行粗体带下划线的 `Assistant` 标题，随后 reasoning 与文本均在第 0 列渲染，timing 行位于块末尾（原先的 `paddingX = 1` 缩进已移除）。
+- 工具卡片去掉 `GutterBox` 包装层。卡片状态（进行中 / 错误 / 成功）对整行标题着色——状态字形（`◌` / `✕` / `✓`）与标题文本共用一种颜色，并同角色标题一样加粗且带下划线——而不再是未着色标题旁的一条彩色竖条。正文无前缀渲染；正文行仍按终端宽度经 `Text` 处理，使过长的原始工具输出换行而非溢出。
+- `GutterBox` 类被删除；没有其他地方使用它。
+
+现在对上述任一区域框选，复制得到的正是消息文本本身。
+
+## Alternatives considered
+
+- **仅在用户消息上保留竖条、在工具卡片上去掉** —— 会让最常被复制的工具输出仍然带有污染。已否决：目标是让整个 transcript 都可复制。
+- **仅在标题行上加一条顶部横线或竖条** —— 正文复制干净，但选中标题时仍会带上一个字形，且相比带下划线的角色标题并未带来额外的区分收益，却重新引入了装饰字符。
+- **用缩进代替竖条对分组正文缩进** —— 前导空格仍会进入剪贴板，无法解决复制问题；已明确排除。
+- **在标题上使用填充背景带**（反色，或 256 色柔和背景）—— 能给每个角色一块强烈的色块，但饱和的 ANSI 填充观感过重，且 256 色是固定色而非随主题重映射。下划线以远更轻的方式提供了同样的逐角色区分。
+
+## Consequences
+
+- 从 transcript 复制粘贴无需用户做任何后处理。这正是本次改动的核心收益。
+- transcript 比 gutter bar 布局更扁平，但每个角色以角色色渲染的粗体带下划线标题加空行分隔，无需任何左缘填充即可让消息边界保持清晰。工具卡片状态仍通过彩色带下划线的字形与标题保持可读。
+- 临时浮层（状态面板、模型选择器、恢复列表）上的制表符边框（`│`）保持不变。它们不属于 transcript 消息内容，且很少被复制。
+- 受影响的 keyless TUI `*.expected.txt` 快照均通过 fixture 回放重新记录（无需 API 密钥；所记录的 LLM 会话未变，仅渲染不同）。交互式启动与一次往返提示已在 tmux 中验证。

apps/cli/src/tui.ts

@@ -11,6 +11,7 @@
  * @module @deepseek-ai/dsh/tui
  */
 
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
   addHarnessSourceSection,
@@ -62,6 +63,7 @@ export async function runTui(config: string | undefined, resumeSessionId: string
   // The bin already loaded the invoking directory's .env; the personal .env
   // only fills what is still unset (process.loadEnvFile never overrides).
   loadEnv(NAME, resolveDshHome())
+  process.env.DSH_BUNDLED_SKILL_DIR = join(SOURCE_ROOT, 'skills')
   // The in-place `/resume` handoff re-execs `dsh` with a normalized `--resume`
   // flag, so the resumed process rehydrates through this same intake. The host
   // is offered only when Node exposes `process.execve` and knows its own entry.

docs/config-catalog.md

@@ -1795,7 +1795,7 @@ export interface TuiThemeConfig {
 }
 ```
 
-Source: [`packages/ui/tui/src/index.ts:302`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/config.ts:117`](../packages/ui/tui/src/config.ts)
 
 ## `@deepseek-ai/dsh-tui-demo`
 

docs/cordis-catalog/services.md

@@ -1902,7 +1902,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi
 abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
 ```
 
-Source: [`packages/ui/tui/src/index.ts:153`](../../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:207`](../../packages/ui/tui/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 

examples/tui-agent/tests/snapshots/bash-terminal-card/terminal.expected.txt

@@ -1,63 +1,54 @@
 terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Use the bash tool to — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=25 bufferRow=25
+cursor hidden column=7 viewportRow=24 bufferRow=24
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Use the bash tool to"
   style 1-20 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ 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
-7| "▌ "
-  style 0-0 fg=bright-blue
-8| <blank>
-9| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-10| " The user wants me to run a simple bash command and then reply with \"DONE\".                         "
-  style 1-74 fg=bright-black italic
-11| <blank>
-12| "▌ "
-  style 0-0 fg=green
-13| "▌ ✓ echo TERMINAL_OK                                                                                "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-19 bold
-14| "▌ Echo TERMINAL_OK to verify terminal access                                                        "
-  style 0-0 fg=green
-  style 2-43 fg=bright-black
-15| "▌ TERMINAL_OK                                                                                       "
-  style 0-0 fg=green
-16| "▌ [exit 0]                                                                                          "
-  style 0-0 fg=green
-  style 2-9 dim
-17| "▌ "
-  style 0-0 fg=green
-18| <blank>
-19| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-20| " The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\".        "
-  style 1-91 fg=bright-black italic
-21| <blank>
-22| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-23| " DONE                                                                                               "
-24| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-25| "                                                                                                    "
-  style 1-1 inverse
-26| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-27| "deepseek-v4-flash  /workspace/project  ↑3.0k ↓115  cache 48%  3% contex"
-  style 0-88 dim
-  style 91-99 dim
-28-35| <blank>
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop.  "
+6| <blank>
+7| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+8| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+9| "The user wants me to run a simple bash command and then reply with \"DONE\".                          "
+  style 0-73 fg=bright-black italic
+10| <blank>
+11| "● Tool / bash / Echo TERMINAL_OK to verify terminal access"
+  style 0-57 fg=green
+12| "$ echo TERMINAL_OK                                                                                  "
+  style 0-17 fg=cyan
+13| "TERMINAL_OK                                                                                         "
+14| "[exit 0]                                                                                            "
+  style 0-7 dim
+15| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+16| <blank>
+17| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+18| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+19| "The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\".         "
+  style 0-90 fg=bright-black italic
+20| "DONE                                                                                                "
+21| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+22| <blank>
+23| "/workspace/project  deepseek-v4-flash  ↑3.0k ↓115  cache 48%  3% contex"
+  style 0-46 fg=bright-blue bold
+  style 49-65 fg=bright-black
+  style 68-88 fg=bright-black
+  style 91-99 fg=bright-black
+24| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse
+25-35| <blank>

examples/tui-agent/tests/snapshots/code-mode-dispatch-spill/terminal.expected.txt

@@ -1,65 +1,57 @@
 terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Using ONE run_code program: call — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=26 bufferRow=26
+cursor hidden column=7 viewportRow=26 bufferRow=26
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Using ONE run_code program: call"
   style 1-32 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ Using ONE run_code program: call the bash tool exactly once with the command seq 1 200 | awk      "
-  style 0-0 fg=bright-blue
-  style 79-99 fg=cyan
-7| "▌ '{printf \"line %04d: the quick brown fox jumps over the lazy dog\\n\", $1}', then return ONLY the   "
-  style 0-0 fg=bright-blue
-  style 2-74 fg=cyan
-8| "▌ number of lines in its output. Reply with just that number 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 write a single run_code program that calls bash exactly once with a specific  "
-  style 1-99 fg=bright-black italic
-13| " command, then returns only the number of lines in its output.                                      "
-  style 1-61 fg=bright-black italic
-14| <blank>
-15| "▌ "
-  style 0-0 fg=green
-16| "▌ ✓ Count lines in seq/awk output                                                                   "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-32 bold
-17| "▌ 200                                                                                               "
-  style 0-0 fg=green
-18| "▌ "
-  style 0-0 fg=green
-19| <blank>
-20| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-21| " The result is 200 lines. The user wants me to reply with just that number and stop.                "
-  style 1-83 fg=bright-black italic
-22| <blank>
-23| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-24| " 200                                                                                                "
-25| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-26| "                                                                                                    "
-  style 1-1 inverse
-27| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-28| "deepseek-v4-flash  /workspace/project  ↑123 ↓208  cache 99%  3% c"
-  style 0-93 dim
-  style 96-99 dim
-29-35| <blank>
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Using ONE run_code program: call the bash tool exactly once with the command seq 1 200 | awk        "
+  style 77-99 fg=cyan
+6| "'{printf \"line %04d: the quick brown fox jumps over the lazy dog\\n\", $1}', then return ONLY the     "
+  style 0-72 fg=cyan
+7| "number of lines in its output. Reply with just that number and stop.                                "
+8| <blank>
+9| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+10| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+11| "The user wants me to write a single run_code program that calls bash exactly once with a specific   "
+  style 0-99 fg=bright-black italic
+12| "command, then returns only the number of lines in its output.                                       "
+  style 0-60 fg=bright-black italic
+13| <blank>
+14| "● Tool / run_code"
+  style 0-16 fg=green
+15| "Count lines in seq/awk output                                                                       "
+16| "200                                                                                                 "
+17| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+18| <blank>
+19| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+20| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+21| "The result is 200 lines. The user wants me to reply with just that number and stop.                 "
+  style 0-82 fg=bright-black italic
+22| "200                                                                                                 "
+23| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+24| <blank>
+25| "/workspace/project  deepseek-v4-flash  ↑123 ↓208  cache 99%  3% c"
+  style 0-52 fg=bright-blue bold
+  style 55-71 fg=bright-black
+  style 74-93 fg=bright-black
+  style 96-99 fg=bright-black
+26| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse
+27-35| <blank>

examples/tui-agent/tests/snapshots/code-mode/terminal.expected.txt

@@ -1,136 +1,140 @@
-terminal 100x36 buffer=normal length=64 base=28 viewport=28
+terminal 100x36 buffer=normal length=62 base=26 viewport=26
 lifecycle started=1 stopped=0 progress=inactive
 title "Using ONE run_code program: call — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=33 bufferRow=61
+cursor hidden column=7 viewportRow=35 bufferRow=61
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Using ONE run_code program: call"
   style 1-32 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ 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
-7| "▌ CODE_TWO. Inside that same program, console.log exactly captured output, then return the two      "
-  style 0-0 fg=bright-blue
-  style 2-9 fg=cyan
-  style 58-72 fg=cyan
-8| "▌ outputs joined with a plus sign. Reply with that joined string only 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 write a single run_code program that:                                         "
-  style 1-36 fg=bright-black italic
-  style 37-44 fg=cyan
-  style 45-58 fg=bright-black italic
-13| " 1. Calls bash tool twice - first with echo CODE_ONE, then with echo CODE_TWO                       "
-  style 1-3 fg=bright-blue
-  style 4-9 fg=bright-black italic
-  style 10-13 fg=cyan
-  style 14-38 fg=bright-black italic
-  style 39-51 fg=cyan
-  style 52-63 fg=bright-black italic
-  style 64-76 fg=cyan
-14| " 2. console.log exactly captured output                                                             "
-  style 1-3 fg=bright-blue
-  style 4-14 fg=cyan
-  style 15-23 fg=bright-black italic
-  style 24-38 fg=cyan
-15| " 3. Returns the two outputs joined with a plus sign                                                 "
-  style 1-3 fg=bright-blue
-  style 4-50 fg=bright-black italic
-16| "                                                                                                    "
-17| " Let me think about the structure. The bash tool returns an object with stdout/stderr. I need to    "
-  style 1-38 fg=bright-black italic
-  style 39-42 fg=cyan
-  style 43-99 fg=bright-black italic
-18| " extract the stdout text from each call.                                                            "
-  style 1-39 fg=bright-black italic
-19| "                                                                                                    "
-20| " Looking at the bash output type:                                                                   "
-  style 1-32 fg=bright-black italic
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Using ONE run_code program: call the bash tool twice — exactly echo CODE_ONE then exactly echo      "
+  style 63-75 fg=cyan
+  style 90-99 fg=cyan
+6| "CODE_TWO. Inside that same program, console.log exactly captured output, then return the two outputs"
+  style 0-7 fg=cyan
+  style 56-70 fg=cyan
+7| "joined with a plus sign. Reply with that joined string only and stop.                               "
+8| <blank>
+9| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+10| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+11| "The user wants me to write a single run_code program that:                                          "
+  style 0-35 fg=bright-black italic
+  style 36-43 fg=cyan
+  style 44-57 fg=bright-black italic
+12| "1. Calls bash tool twice - first with echo CODE_ONE, then with echo CODE_TWO                        "
+  style 0-2 fg=bright-blue
+  style 3-8 fg=bright-black italic
+  style 9-12 fg=cyan
+  style 13-37 fg=bright-black italic
+  style 38-50 fg=cyan
+  style 51-62 fg=bright-black italic
+  style 63-75 fg=cyan
+13| "2. console.log exactly captured output                                                              "
+  style 0-2 fg=bright-blue
+  style 3-13 fg=cyan
+  style 14-22 fg=bright-black italic
+  style 23-37 fg=cyan
+14| "3. Returns the two outputs joined with a plus sign                                                  "
+  style 0-2 fg=bright-blue
+  style 3-49 fg=bright-black italic
+15| "                                                                                                    "
+16| "Let me think about the structure. The bash tool returns an object with stdout/stderr. I need to     "
+  style 0-37 fg=bright-black italic
+  style 38-41 fg=cyan
+  style 42-99 fg=bright-black italic
+17| "extract the stdout text from each call.                                                             "
+  style 0-38 fg=bright-black italic
+18| "                                                                                                    "
+19| "Looking at the bash output type:                                                                    "
+  style 0-31 fg=bright-black italic
+20| "                                                                                                    "
 21| "                                                                                                    "
-22| " ```                                                                                                "
-  style 1-3 dim
-23| "   {                                                                                                "
-24| "     kind: \"foreground\";                                                                            "
-25| "     exitCode: number | null;                                                                       "
-26| "     signal: string | null;                                                                         "
-27| "     timedOut: boolean;                                                                             "
-28| "     aborted: boolean;                                                                              "
-29| "     timeoutMs: number;                                                                             "
-30| "     stdout: {                                                                                      "
-31| "       text: string;                                                                                "
-32| "       truncated: boolean;                                                                          "
-33| "       spillPath?: string;                                                                          "
-34| "     };                                                                                             "
-35| "     stderr: { ... };                                                                               "
-36| "     sandbox?: { ... };                                                                             "
-37| "   }                                                                                                "
-38| " ```                                                                                                "
-  style 1-3 dim
-39| "                                                                                                    "
-40| " So I need to access .stdout.text from each result.                                                 "
-  style 1-20 fg=bright-black italic
-  style 21-32 fg=cyan
-  style 33-50 fg=bright-black italic
-41| "                                                                                                    "
-42| " Let me write the program.                                                                          "
-  style 1-25 fg=bright-black italic
-43| <blank>
-44| "▌ "
-  style 0-0 fg=green
-45| "▌ ✓ Call bash twice, log, join outputs                                                              "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-37 bold
-46| "▌ captured output                                                                                   "
-  style 0-0 fg=green
-47| "▌ CODE_ONE+CODE_TWO                                                                                 "
-  style 0-0 fg=green
-48| "▌ "
-  style 0-0 fg=green
-49| <blank>
-50| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-51| " The program ran successfully. The output shows:                                                    "
-  style 1-47 fg=bright-black italic
-52| " - captured output (from console.log)                                                               "
-  style 1-2 fg=bright-blue
-  style 3-17 fg=cyan
-  style 18-36 fg=bright-black italic
-53| " - CODE_ONE+CODE_TWO (the returned joined string)                                                   "
-  style 1-2 fg=bright-blue
-  style 3-19 fg=cyan
-  style 20-48 fg=bright-black italic
+22| "  {                                                                                                 "
+  style 2-2 fg=cyan
+23| "    kind: \"foreground\";                                                                             "
+  style 2-22 fg=cyan
+24| "    exitCode: number | null;                                                                        "
+  style 2-27 fg=cyan
+25| "    signal: string | null;                                                                          "
+  style 2-25 fg=cyan
+26| "    timedOut: boolean;                                                                              "
+  style 2-21 fg=cyan
+27| "    aborted: boolean;                                                                               "
+  style 2-20 fg=cyan
+28| "    timeoutMs: number;                                                                              "
+  style 2-21 fg=cyan
+29| "    stdout: {                                                                                       "
+  style 2-12 fg=cyan
+30| "      text: string;                                                                                 "
+  style 2-18 fg=cyan
+31| "      truncated: boolean;                                                                           "
+  style 2-24 fg=cyan
+32| "      spillPath?: string;                                                                           "
+  style 2-24 fg=cyan
+33| "    };                                                                                              "
+  style 2-5 fg=cyan
+34| "    stderr: { ... };                                                                                "
+  style 2-19 fg=cyan
+35| "    sandbox?: { ... };                                                                              "
+  style 2-21 fg=cyan
+36| "  }                                                                                                 "
+  style 2-2 fg=cyan
+37| "                                                                                                    "
+38| "                                                                                                    "
+39| "So I need to access .stdout.text from each result.                                                  "
+  style 0-19 fg=bright-black italic
+  style 20-31 fg=cyan
+  style 32-49 fg=bright-black italic
+40| "                                                                                                    "
+41| "Let me write the program.                                                                           "
+  style 0-24 fg=bright-black italic
+42| <blank>
+43| "● Tool / run_code"
+  style 0-16 fg=green
+44| "Call bash twice, log, join outputs                                                                  "
+45| "captured output                                                                                     "
+46| "CODE_ONE+CODE_TWO                                                                                   "
+47| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+48| <blank>
+49| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+50| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+51| "The program ran successfully. The output shows:                                                     "
+  style 0-46 fg=bright-black italic
+52| "- captured output (from console.log)                                                                "
+  style 0-1 fg=bright-blue
+  style 2-16 fg=cyan
+  style 17-35 fg=bright-black italic
+53| "- CODE_ONE+CODE_TWO (the returned joined string)                                                    "
+  style 0-1 fg=bright-blue
+  style 2-18 fg=cyan
+  style 19-47 fg=bright-black italic
 54| "                                                                                                    "
-55| " The user asked me to reply with that joined string only and stop. So I'll reply with just          "
-  style 1-99 fg=bright-black italic
-56| " CODE_ONE+CODE_TWO.                                                                                 "
-  style 1-17 fg=cyan
-  style 18-18 fg=bright-black italic
-57| <blank>
-58| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-59| " CODE_ONE+CODE_TWO                                                                                  "
-60| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-61| "                                                                                                    "
-  style 1-1 inverse
-62| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-63| "deepseek-v4-flash  /workspace/project  ↑182 ↓446  cache 98%  4% context  tools:c"
-  style 0-78 dim
-  style 81-99 dim
+55| "The user asked me to reply with that joined string only and stop. So I'll reply with just           "
+  style 0-99 fg=bright-black italic
+56| "CODE_ONE+CODE_TWO.                                                                                  "
+  style 0-16 fg=cyan
+  style 17-17 fg=bright-black italic
+57| "CODE_ONE+CODE_TWO                                                                                   "
+58| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+59| <blank>
+60| "/workspace/project  deepseek-v4-flash  ↑182 ↓446  cache 98%  4% context"
+  style 0-37 fg=bright-blue bold
+  style 40-56 fg=bright-black
+  style 59-78 fg=bright-black
+  style 81-90 fg=bright-black
+61| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse

examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.expected.txt

@@ -1,106 +1,93 @@
-terminal 100x36 buffer=normal length=48 base=12 viewport=12
+terminal 100x36 buffer=normal length=57 base=21 viewport=21
 lifecycle started=1 stopped=0 progress=inactive
 title "Run this advanced flow exactly — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=33 bufferRow=45
+cursor hidden column=7 viewportRow=35 bufferRow=56
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Run this advanced flow exactly"
   style 1-30 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use       "
-  style 0-0 fg=bright-blue
-7| "▌ run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a      "
-  style 0-0 fg=bright-blue
-8| "▌ direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then   "
-  style 0-0 fg=bright-blue
-9| "▌ reply with exactly ADVANCED_ACP_OK.                                                               "
-  style 0-0 fg=bright-blue
-10| "▌ "
-  style 0-0 fg=bright-blue
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code"
+6| "to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn    "
+7| "child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with       "
+8| "exactly ADVANCED_ACP_OK.                                                                            "
+9| <blank>
+10| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
 11| <blank>
-12| "▌ "
-  style 0-0 fg=green
-13| "▌ ✓ Mount plugin into live cordis runtime                                                           "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-40 bold
-14| "▌ mounted dyn-1 (plugin \"snapshot-marker\", state: active)                                           "
-  style 0-0 fg=green
-15| "▌ "
-  style 0-0 fg=green
+12| "● Tool / cordis_mount"
+  style 0-20 fg=green
+13| "Mount plugin into live cordis runtime                                                               "
+14| "mounted dyn-1 (plugin \"snapshot-marker\", state: active)                                             "
+15| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
 16| <blank>
-17| "▌ "
-  style 0-0 fg=green
-18| "▌ ✓ Verify the dynamically mounted marker service                                                   "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-48 bold
-19| "▌ ## dynamic                                                                                        "
-  style 0-0 fg=green
-20| "▌ - dyn-1: snapshot-marker [active]                                                                 "
-  style 0-0 fg=green
-21| "▌ "
-  style 0-0 fg=green
-22| <blank>
-23| "▌ "
-  style 0-0 fg=green
-24| "▌ ✓ subagent                                                                                        "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-11 bold
-25| "▌ DIRECT_CHILD_OK                                                                                   "
-  style 0-0 fg=green
-26| "▌ "
-  style 0-0 fg=green
-27| <blank>
-28| "▌ "
-  style 0-0 fg=green
-29| "▌ ✓ workflow: advanced-acp-snapshot                                                                 "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-34 bold
-30| "▌ workflow \"advanced-acp-snapshot\" completed (1 agent).                                             "
-  style 0-0 fg=green
-31| "▌ Return value:                                                                                     "
-  style 0-0 fg=green
-32| "▌ {                                                                                                 "
-  style 0-0 fg=green
-33| "▌   \"reply\": \"WORKFLOW_CHILD_OK\"                                                                    "
-  style 0-0 fg=green
-34| "▌ }                                                                                                 "
-  style 0-0 fg=green
-35| "▌ "
-  style 0-0 fg=green
-36| <blank>
-37| "▌ "
-  style 0-0 fg=green
-38| "▌ ✓ Unmount dyn-1                                                                                   "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-16 bold
-39| "▌ unmounted dyn-1 (plugin \"snapshot-marker\")                                                        "
-  style 0-0 fg=green
-40| "▌ "
-  style 0-0 fg=green
-41| <blank>
-42| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-43| " ADVANCED_ACP_OK                                                                                    "
-44| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-45| "                                                                                                    "
-  style 1-1 inverse
-46| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-47| "deepseek-v4-flash  /workspace/project  ↑18 ↓18  cache 0%  8% cont"
-  style 0-90 dim
-  style 93-99 dim
+17| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+18| <blank>
+19| "● Tool / run_code"
+  style 0-16 fg=green
+20| "Verify the dynamically mounted marker service                                                       "
+21| "                                                                                                    "
+22| "dynamic                                                                                             "
+  style 0-6 fg=bright-blue bold
+23| "                                                                                                    "
+24| "- dyn-1: snapshot-marker [active]                                                                   "
+  style 0-1 fg=bright-blue
+25| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+26| <blank>
+27| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+28| <blank>
+29| "● Tool / subagent"
+  style 0-16 fg=green
+30| "DIRECT_CHILD_OK                                                                                     "
+31| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+32| <blank>
+33| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+34| <blank>
+35| "● Tool / workflow"
+  style 0-16 fg=green
+36| "workflow: advanced-acp-snapshot                                                                     "
+37| "workflow \"advanced-acp-snapshot\" completed (1 agent).                                               "
+38| "Return value:                                                                                       "
+39| "{                                                                                                   "
+40| "  \"reply\": \"WORKFLOW_CHILD_OK\"                                                                      "
+41| "}                                                                                                   "
+42| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+43| <blank>
+44| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+45| <blank>
+46| "● Tool / cordis_unmount"
+  style 0-22 fg=green
+47| "Unmount dyn-1                                                                                       "
+48| "unmounted dyn-1 (plugin \"snapshot-marker\")                                                          "
+49| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+50| <blank>
+51| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+52| "ADVANCED_ACP_OK                                                                                     "
+53| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+54| <blank>
+55| "/workspace/project  deepseek-v4-flash  ↑18 ↓18  cache 0%  8% cont"
+  style 0-52 fg=bright-blue bold
+  style 55-71 fg=bright-black
+  style 74-90 fg=bright-black
+  style 93-99 fg=bright-black
+56| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse

examples/tui-agent/tests/snapshots/dynamic-workflow/terminal.expected.txt

@@ -1,96 +1,80 @@
-terminal 100x36 buffer=normal length=45 base=9 viewport=9
+terminal 100x36 buffer=normal length=43 base=7 viewport=7
 lifecycle started=1 stopped=0 progress=inactive
 title "Use the workflow tool exactly — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=33 bufferRow=42
+cursor hidden column=7 viewportRow=35 bufferRow=42
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Use the workflow tool exactly"
   style 1-29 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\",     "
-  style 0-0 fg=bright-blue
-7| "▌ \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):     "
-  style 0-0 fg=bright-blue
-8| "▌ phase('Run')                                                                                      "
-  style 0-0 fg=bright-blue
-9| "▌ const reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')            "
-  style 0-0 fg=bright-blue
-10| "▌ return { reply }                                                                                  "
-  style 0-0 fg=bright-blue
-11| "▌ After the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any     "
-  style 0-0 fg=bright-blue
-12| "▌ other tool.                                                                                       "
-  style 0-0 fg=bright-blue
-13| "▌ "
-  style 0-0 fg=bright-blue
-14| <blank>
-15| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-16| " The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully "
-  style 1-99 fg=bright-black italic
-17| " follow the instructions:                                                                           "
-  style 1-24 fg=bright-black italic
-18| "                                                                                                    "
-19| " 1. args omitted (so I don't include it)                                                            "
-  style 1-3 fg=bright-blue
-  style 4-39 fg=bright-black italic
-20| " 2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }                 "
-  style 1-3 fg=bright-blue
-  style 4-82 fg=bright-black italic
-21| " 3. script = as given verbatim                                                                      "
-  style 1-3 fg=bright-blue
-  style 4-29 fg=bright-black italic
-22| " 4. After it returns, reply with \"WORKFLOW_DONE\"                                                    "
-  style 1-3 fg=bright-blue
-  style 4-47 fg=bright-black italic
-23| "                                                                                                    "
-24| " Let me do exactly that.                                                                            "
-  style 1-23 fg=bright-black italic
-25| <blank>
-26| "▌ "
-  style 0-0 fg=green
-27| "▌ ✓ workflow: snapshot-flow                                                                         "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-26 bold
-28| "▌ workflow \"snapshot-flow\" completed (1 agent).                                                     "
-  style 0-0 fg=green
-29| "▌ Return value:                                                                                     "
-  style 0-0 fg=green
-30| "▌ {                                                                                                 "
-  style 0-0 fg=green
-31| "▌   \"reply\": \"WF_CHILD_OK\"                                                                          "
-  style 0-0 fg=green
-32| "▌ }                                                                                                 "
-  style 0-0 fg=green
-33| "▌ "
-  style 0-0 fg=green
-34| <blank>
-35| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-36| " The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly  "
-  style 1-99 fg=bright-black italic
-37| " \"WORKFLOW_DONE\" and stop.                                                                          "
-  style 1-25 fg=bright-black italic
-38| <blank>
-39| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-40| " WORKFLOW_DONE                                                                                      "
-41| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-42| "                                                                                                    "
-  style 1-1 inverse
-43| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-44| "deepseek-v4-flash  /workspace/project  ↑3.5k ↓227  cache 47%  3% context "
-  style 0-86 dim
-  style 89-99 dim
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\",       "
+6| "\"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):       "
+7| "phase('Run')                                                                                        "
+8| "const reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')              "
+9| "return { reply }                                                                                    "
+10| "After the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other "
+11| "tool.                                                                                               "
+12| <blank>
+13| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+14| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+15| "The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully  "
+  style 0-99 fg=bright-black italic
+16| "follow the instructions:                                                                            "
+  style 0-23 fg=bright-black italic
+17| "                                                                                                    "
+18| "1. args omitted (so I don't include it)                                                             "
+  style 0-2 fg=bright-blue
+  style 3-38 fg=bright-black italic
+19| "2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }                  "
+  style 0-2 fg=bright-blue
+  style 3-81 fg=bright-black italic
+20| "3. script = as given verbatim                                                                       "
+  style 0-2 fg=bright-blue
+  style 3-28 fg=bright-black italic
+21| "4. After it returns, reply with \"WORKFLOW_DONE\"                                                     "
+  style 0-2 fg=bright-blue
+  style 3-46 fg=bright-black italic
+22| "                                                                                                    "
+23| "Let me do exactly that.                                                                             "
+  style 0-22 fg=bright-black italic
+24| <blank>
+25| "● Tool / workflow"
+  style 0-16 fg=green
+26| "workflow: snapshot-flow                                                                             "
+27| "workflow \"snapshot-flow\" completed (1 agent).                                                       "
+28| "Return value:                                                                                       "
+29| "{                                                                                                   "
+30| "  \"reply\": \"WF_CHILD_OK\"                                                                            "
+31| "}                                                                                                   "
+32| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+33| <blank>
+34| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+35| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+36| "The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly   "
+  style 0-99 fg=bright-black italic
+37| "\"WORKFLOW_DONE\" and stop.                                                                           "
+  style 0-24 fg=bright-black italic
+38| "WORKFLOW_DONE                                                                                       "
+39| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+40| <blank>
+41| "/workspace/project  deepseek-v4-flash  ↑3.5k ↓227  cache 47%  3% context"
+  style 0-44 fg=bright-blue bold
+  style 47-63 fg=bright-black
+  style 66-86 fg=bright-black
+  style 89-98 fg=bright-black
+42| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse

examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.expected.txt

@@ -1,70 +1,62 @@
 terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Reply with exactly the word: — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=33 bufferRow=33
+cursor hidden column=7 viewportRow=30 bufferRow=30
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Reply with exactly the word:"
   style 1-28 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| " Entering plan mode (applies from the next step). Use /plan off to leave.                           "
-  style 1-72 fg=bright-black
+4| "Entering plan mode (applies from the next step). Use /plan off to leave.                            "
+  style 0-71 fg=bright-black
 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                                                                                                "
+6| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+7| "Reply with exactly the word: ONE. No tools.                                                         "
+8| <blank>
+9| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+10| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+11| "The user wants me to reply with exactly the word \"ONE\" and use no tools.                            "
+  style 0-71 fg=bright-black italic
+12| "ONE                                                                                                 "
+13| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+14| <blank>
+15| "Leaving plan mode (applies from the next step).                                                     "
+  style 0-46 fg=bright-black
 16| <blank>
-17| " Leaving plan mode (applies from the next step).                                                    "
-  style 1-47 fg=bright-black
-18| <blank>
-19| " Context · plan-mode                                                                                "
-  style 1-19 dim
-20| " The user switched this session back to the default mode.                                           "
-  style 1-56 fg=bright-black
-21| <blank>
-22| "▌ "
-  style 0-0 fg=bright-blue
-23| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-24| "▌ Reply with exactly the word: TWO. No tools.                                                       "
-  style 0-0 fg=bright-blue
-25| "▌ "
-  style 0-0 fg=bright-blue
-26| <blank>
-27| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-28| " The user wants me to reply with exactly the word \"TWO\" and no tools.                               "
-  style 1-68 fg=bright-black italic
-29| <blank>
-30| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-31| " TWO                                                                                                "
-32| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-33| "                                                                                                    "
-  style 1-1 inverse
-34| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-35| "deepseek-v4-flash  /workspace/project  ↑2.9k ↓41  cache 49%  3% co"
-  style 0-92 dim
-  style 95-99 dim
+17| "Context · plan-mode                                                                                 "
+  style 0-18 dim
+18| "The user switched this session back to the default mode.                                            "
+  style 0-55 fg=bright-black
+19| <blank>
+20| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+21| "Reply with exactly the word: TWO. No tools.                                                         "
+22| <blank>
+23| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+24| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+25| "The user wants me to reply with exactly the word \"TWO\" and no tools.                                "
+  style 0-67 fg=bright-black italic
+26| "TWO                                                                                                 "
+27| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+28| <blank>
+29| "/workspace/project  deepseek-v4-flash  ↑2.9k ↓41  cache 49%  3% co"
+  style 0-51 fg=bright-blue bold
+  style 54-70 fg=bright-black
+  style 73-92 fg=bright-black
+  style 95-99 fg=bright-black
+30| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse
+31-35| <blank>

examples/tui-agent/tests/snapshots/parallel-file-reads/terminal.expected.txt

@@ -1,81 +1,52 @@
-terminal 100x36 buffer=normal length=37 base=1 viewport=1
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Use the read tool twice — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=33 bufferRow=34
+cursor hidden column=7 viewportRow=27 bufferRow=27
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Use the read tool twice"
   style 1-23 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ 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
-7| "▌ "
-  style 0-0 fg=bright-blue
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Use the read tool twice in the same assistant message: read a.txt and b.txt. Then reply DONE.       "
+6| <blank>
+7| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
 8| <blank>
-9| "▌ "
-  style 0-0 fg=green
-10| "▌ ✓ Read a.txt                                                                                      "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-13 bold
-11| "▌ <path>/workspace/project/a.txt</path>                               "
-  style 0-0 fg=green
-12| "▌ <type>file</type>                                                                                 "
-  style 0-0 fg=green
-13| "▌ <content>                                                                                         "
-  style 0-0 fg=green
-14| "▌ 1: alpha                                                                                          "
-  style 0-0 fg=green
-15| "▌                                                                                                   "
-  style 0-0 fg=green
-16| "▌ (End of file - total 1 lines)                                                                     "
-  style 0-0 fg=green
-17| "▌ </content>                                                                                        "
-  style 0-0 fg=green
-18| "▌ "
-  style 0-0 fg=green
-19| <blank>
-20| "▌ "
-  style 0-0 fg=green
-21| "▌ ✓ Read b.txt                                                                                      "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-13 bold
-22| "▌ <path>/workspace/project/b.txt</path>                               "
-  style 0-0 fg=green
-23| "▌ <type>file</type>                                                                                 "
-  style 0-0 fg=green
-24| "▌ <content>                                                                                         "
-  style 0-0 fg=green
-25| "▌ 1: beta                                                                                           "
-  style 0-0 fg=green
-26| "▌                                                                                                   "
-  style 0-0 fg=green
-27| "▌ (End of file - total 1 lines)                                                                     "
-  style 0-0 fg=green
-28| "▌ </content>                                                                                        "
-  style 0-0 fg=green
-29| "▌ "
-  style 0-0 fg=green
-30| <blank>
-31| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-32| " DONE                                                                                               "
-33| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-34| "                                                                                                    "
-  style 1-1 inverse
-35| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-36| "deepseek-v4-flash  /workspace/project  ↑20 ↓6  cache 0%  3% context  t"
-  style 0-84 dim
-  style 87-99 dim
+9| "● Tool / read"
+  style 0-12 fg=green
+10| "Read a.txt                                                                                          "
+11| "1: alpha                                                                                            "
+12| "                                                                                                    "
+13| "(End of file - total 1 lines)                                                                       "
+14| <blank>
+15| "● Tool / read"
+  style 0-12 fg=green
+16| "Read b.txt                                                                                          "
+17| "1: beta                                                                                             "
+18| "                                                                                                    "
+19| "(End of file - total 1 lines)                                                                       "
+20| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+21| <blank>
+22| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+23| "DONE                                                                                                "
+24| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+25| <blank>
+26| "/workspace/project  deepseek-v4-flash  ↑20 ↓6  cache 0%  3% context"
+  style 0-47 fg=bright-blue bold
+  style 50-66 fg=bright-black
+  style 69-84 fg=bright-black
+  style 87-96 fg=bright-black
+27| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse
+28-35| <blank>

examples/tui-agent/tests/snapshots/todo-plan/terminal.expected.txt

@@ -1,57 +1,48 @@
 terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Use the todo_write tool to — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=31 bufferRow=31
+cursor hidden column=7 viewportRow=31 bufferRow=31
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
   style 10-16 bold
 1| " Use the todo_write tool to"
   style 1-26 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
+2| " main-session"
+  style 1-12 dim
 3| <blank>
-4| "▌ "
-  style 0-0 fg=bright-blue
-5| "▌ You                                                                                               "
-  style 0-0 fg=bright-blue
-  style 2-4 fg=bright-blue bold
-6| "▌ Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), "
-  style 0-0 fg=bright-blue
-7| "▌ \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then "
-  style 0-0 fg=bright-blue
-8| "▌ 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 use the todo_write tool to record a plan with exactly three todos in the      "
-  style 1-99 fg=bright-black italic
-13| " specified statuses, then reply with \"DONE\".                                                        "
-  style 1-43 fg=bright-black italic
-14| <blank>
-15| "▌ "
-  style 0-0 fg=green
-16| "▌ ✓ Update todo list                                                                                "
-  style 0-0 fg=green
-  style 2-2 fg=green bold
-  style 3-19 bold
-17| "▌ Updated todo list: 2 pending, 1 in progress, 0 completed.                                         "
-  style 0-0 fg=green
-18| "▌ "
-  style 0-0 fg=green
-19| <blank>
-20| " Reasoning                                                                                          "
-  style 1-9 fg=bright-black italic
-21| " The todos have been written successfully. Now I just need to reply with the single word \"DONE\".    "
-  style 1-95 fg=bright-black italic
-22| <blank>
-23| " Assistant                                                                                          "
-  style 1-9 fg=bright-magenta bold
-24| " DONE                                                                                               "
-25| <blank>
+4| "You                                                                                                 "
+  style 0-2 fg=bright-blue bold underline
+5| "Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress),   "
+6| "\"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then   "
+7| "reply with the single word DONE and stop.                                                           "
+8| <blank>
+9| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+10| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+11| "The user wants me to use the todo_write tool to record a plan with exactly three todos in the       "
+  style 0-99 fg=bright-black italic
+12| "specified statuses, then reply with \"DONE\".                                                         "
+  style 0-42 fg=bright-black italic
+13| <blank>
+14| "● Tool / todo_write"
+  style 0-18 fg=green
+15| "Update todo list                                                                                    "
+16| "Updated todo list: 2 pending, 1 in progress, 0 completed.                                           "
+17| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+18| <blank>
+19| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+20| "Reasoning                                                                                           "
+  style 0-8 fg=bright-black italic
+21| "The todos have been written successfully. Now I just need to reply with the single word \"DONE\".     "
+  style 0-94 fg=bright-black italic
+22| "DONE                                                                                                "
+23| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+24-25| <blank>
 26| "Plan"
   style 0-3 fg=bright-blue bold
 27| "  ● read the code"
@@ -60,13 +51,13 @@ buffer
   style 2-2 dim
 29| "  ○ run the tests"
   style 2-2 dim
-30| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-31| "                                                                                                    "
-  style 1-1 inverse
-32| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-33| "deepseek-v4-flash  /workspace/project  ↑3.1k ↓145  cache 47%  3% context  tools:"
-  style 0-79 dim
-  style 82-99 dim
-34-35| <blank>
+30| "/workspace/project  deepseek-v4-flash  ↑3.1k ↓145  cache 47%  3% context"
+  style 0-37 fg=bright-blue bold
+  style 40-56 fg=bright-black
+  style 59-79 fg=bright-black
+  style 82-91 fg=bright-black
+31| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-blue bold
+  style 5-6 fg=bright-black
+  style 7-7 inverse
+32-35| <blank>

examples/tui-agent/tests/tui-keyless-smoke.e2e.ts

@@ -72,7 +72,14 @@ async function seedResumeSession(cwd: string): Promise<void> {
 }
 
 /** The rendered system prompt from the first `request/header` in the workspace's persisted session log. */
-async function readLoggedSystemPrompt(cwd: string): Promise<string> {
+interface LoggedRequestHeader {
+  /** The system prompt string the launcher sends. */
+  system: string
+  /** The baked session-prefix messages (skill catalog, workspace context) serialized to text. */
+  prefix: string
+}
+
+async function readLoggedRequestHeader(cwd: string): Promise<LoggedRequestHeader> {
   const sessionsDir = join(cwd, '.sessions')
   const entries = await readdir(sessionsDir, { recursive: true })
   // A single keyless run writes one session log; the source section is global, so any log carries it.
@@ -80,8 +87,16 @@ async function readLoggedSystemPrompt(cwd: string): Promise<string> {
   if (logRelPath === undefined) throw new Error(`no session log written under ${sessionsDir}`)
   const lines = (await readFile(join(sessionsDir, logRelPath), 'utf8')).split('\n').filter(Boolean)
   for (const line of lines) {
-    const event = JSON.parse(line) as { type: string; data: { header?: { system?: string } } }
-    if (event.type === 'request/header') return event.data.header?.system ?? ''
+    const event = JSON.parse(line) as {
+      type: string
+      data: { header?: { system?: string; messagePrefix?: unknown } }
+    }
+    if (event.type === 'request/header') {
+      return {
+        system: event.data.header?.system ?? '',
+        prefix: JSON.stringify(event.data.header?.messagePrefix ?? []),
+      }
+    }
   }
   throw new Error(`session log ${logRelPath} has no request/header event`)
 }
@@ -176,6 +191,10 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
     expect(output).toContain('KV cache')
     expect(output).toContain('Context')
     expect(output).toContain('128,000')
+    expect(output).toContain('System prompt')
+    expect(output).toContain('You are an AI agent powered by the DeepSeek Harness SDK.')
+    expect(output).toContain('Registered tools')
+    expect(output).toContain('ask_user_question')
     expect(output).toContain('\u001B[?2004l')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
@@ -208,6 +227,7 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
         { waitFor: 'Scripted skill body received.', send: '/exit\r' },
       ],
     })
+    expect(output).not.toContain('[instructions]')
     expect(output).toContain('Scripted skill body received.')
     expect(output).toContain('\u001B[?2004l')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
@@ -342,11 +362,13 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('ui-tui: session "missing-session" failed to start:')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('tells the model where its own source lives, in the system prompt it sends', async () => {
+  it('tells the model its source path and offers the bundled maintenance skills', async () => {
     // The launcher resolves the checkout root three hops up from apps/cli/{src,lib};
     // this test file sits an equal depth under the same root, so the same hop applies.
+    // The source-path line is a system-prompt section; the bundled skills reach the
+    // model through the session-prefix catalog, so each assertion targets its own field.
     const sourceRoot = fileURLToPath(new URL('../../..', import.meta.url))
-    let loggedSystem = ''
+    let header: LoggedRequestHeader = { system: '', prefix: '' }
     await smoke({
       label: 'dsh source-path prompt',
       tempDirPrefix: 'dsh-source-path-',
@@ -358,8 +380,11 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
         { waitFor: 'How should the scripted run proceed?', send: '\r' },
         { waitFor: 'Decision received. Scripted TUI run complete.', send: '/exit\r' },
       ],
-      inspect: async (cwd) => { loggedSystem = await readLoggedSystemPrompt(cwd) },
+      inspect: async (cwd) => { header = await readLoggedRequestHeader(cwd) },
     })
-    expect(loggedSystem).toContain(`Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`)
+    expect(header.system).toContain(`Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`)
+    expect(header.prefix).toContain('- `dsh-customize`: Customize a dsh installation. Use before any requested change that potentailly impacts the checkout that powers the current DSH process or installed `dsh` command, including code, docs, skills, configuration, tests, commit history, or PR-branch updates; do not edit the personal staging checkout directly.')
+    expect(header.prefix).toContain('- `dsh-upgrade`: Upgrades a source-installed, personally customized DSH checkout to upstream master while preserving local changes and an unchanged rollback checkout. Use when the user asks to update or upgrade DSH.')
+    expect(header.prefix).toContain('- `dsh-upstream-customization`: Classifies personal DSH customizations for upstream contribution and, after explicit per-feature approval, rebuilds one on upstream master and opens a draft pull request. Use when the user asks to contribute, publish, or upstream a local DSH change, or asks whether one is worth proposing.')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })

examples/tui-agent/tests/tui.snapshot.ts

@@ -2,7 +2,7 @@ import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/pr
 import { tmpdir } from 'node:os'
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { afterAll, describe, expect, it } from 'vitest'
+import { afterAll, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { scrubRequestHeaders } from '@deepseek-ai/dsh-acp-snapshot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -25,7 +25,7 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as ToolRalph from '@deepseek-ai/dsh-tool-ralph'
 import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
-import { createTuiChat, FILE_REFERENCE_PROMPT } from '@deepseek-ai/dsh-tui'
+import { createTuiChat, FILE_REFERENCE_PROMPT, TuiPromptService } from '@deepseek-ai/dsh-tui'
 import LocalSpillStore from '@deepseek-ai/dsh-spill-local'
 import * as SpillPolicy from '@deepseek-ai/dsh-spill-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -225,6 +225,7 @@ async function mountScenarioContext(
   await ctx.plugin(FsPolicy)
   await ctx.plugin(ToolFs)
   await ctx.plugin(UserInteractionService)
+  await ctx.plugin(TuiPromptService)
   // todo_write is opt-in: only the todo-plan scenario mounts it, matching the shipped
   // config that omits it. The other scenarios prove the default todo-free composition.
   if (scenario.enableTodo === true) await ctx.plugin(ToolTodo)
@@ -262,6 +263,7 @@ interface ScenarioResult {
 }
 
 async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
+  const clock = vi.spyOn(Date, 'now').mockReturnValue(new Date(2026, 6, 21, 12, 0, 0).getTime())
   const dir = scenarioDir(scenario)
   const fixtureFile = join(dir, 'session.jsonl')
   const childFiles = childFixturePaths(scenario)
@@ -294,7 +296,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
     const agent: Agent = handle.agent
     controller = createTuiChat(ctx, {
       sessionId: 'main-session',
-      color: true,
+      theme: { color: true },
       showReasoning: true,
       title: 'DSH TUI snapshot',
       welcome: `Recorded replay: ${scenario.name}`,
@@ -404,6 +406,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
     await ctx?.fiber.dispose()
     await terminal.dispose()
     await rm(cwd, { recursive: true, force: true })
+    clock.mockRestore()
   }
 }
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -2443,58 +2443,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ToolSchema',
     declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',
   },
-  {
-    name: 'TuiComponent',
-    declaration: 'export interface TuiComponent {\n    render(width: number): string[];\n    handleInput?(data: string): void;\n    wantsKeyRelease?: boolean;\n    invalidate(): void;\n}',
-  },
-  {
-    name: 'TuiFocusable',
-    declaration: 'export interface TuiFocusable {\n    focused: boolean;\n}',
-  },
-  {
-    name: 'TuiOverlayAnchor',
-    declaration: 'export type TuiOverlayAnchor = \'center\' | \'top-left\' | \'top-right\' | \'bottom-left\' | \'bottom-right\' | \'top-center\' | \'bottom-center\' | \'left-center\' | \'right-center\';',
-  },
-  {
-    name: 'TuiOverlayCloseReason',
-    declaration: 'export type TuiOverlayCloseReason = \'closed\' | \'aborted\' | \'owner-disposed\' | \'tui-disposed\' | \'error\';',
-  },
-  {
-    name: 'TuiOverlayHost',
-    declaration: 'export interface TuiOverlayHost {\n    readonly signal: AbortSignal;\n    readonly viewport: TuiViewport;\n    readonly theme: TuiTheme;\n    display(value: string): string;\n    invalidate(): void;\n    close(): void;\n}',
-  },
-  {
-    name: 'TuiOverlayMargin',
-    declaration: 'export interface TuiOverlayMargin {\n    readonly top?: number;\n    readonly right?: number;\n    readonly bottom?: number;\n    readonly left?: number;\n}',
-  },
-  {
-    name: 'TuiOverlayOptions',
-    declaration: 'export interface TuiOverlayOptions {\n    readonly width?: number | `${number}%`;\n    readonly minWidth?: number;\n    readonly maxHeight?: number | `${number}%`;\n    readonly anchor?: TuiOverlayAnchor;\n    readonly margin?: number | TuiOverlayMargin;\n}',
-  },
-  {
-    name: 'TuiOverlayOutcome',
-    declaration: 'export type TuiOverlayOutcome = {\n    readonly reason: Exclude<TuiOverlayCloseReason, \'error\'>;\n} | {\n    readonly reason: \'error\';\n    readonly error: unknown;\n};',
-  },
-  {
-    name: 'TuiOverlayRequest',
-    declaration: 'export interface TuiOverlayRequest {\n    readonly create: (host: TuiOverlayHost) => TuiComponent & Partial<TuiFocusable>;\n    readonly options?: TuiOverlayOptions;\n    readonly signal?: AbortSignal;\n}',
-  },
-  {
-    name: 'TuiOverlaySession',
-    declaration: 'export interface TuiOverlaySession {\n    readonly state: TuiOverlayState;\n    readonly closed: Promise<TuiOverlayOutcome>;\n    close(): Promise<TuiOverlayOutcome>;\n}',
-  },
-  {
-    name: 'TuiOverlayState',
-    declaration: 'export type TuiOverlayState = \'queued\' | \'active\' | \'closed\';',
-  },
-  {
-    name: 'TuiTheme',
-    declaration: 'export interface TuiTheme {\n    readonly text: (value: string) => string;\n    readonly muted: (value: string) => string;\n    readonly dim: (value: string) => string;\n    readonly accent: (value: string) => string;\n    readonly success: (value: string) => string;\n    readonly warning: (value: string) => string;\n    readonly error: (value: string) => string;\n    readonly bold: (value: string) => string;\n}',
-  },
-  {
-    name: 'TuiViewport',
-    declaration: 'export interface TuiViewport {\n    readonly columns: number;\n    readonly rows: number;\n}',
-  },
   {
     name: 'TurnEndReason',
     declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];',

packages/examples/tui-demo/src/index.ts

@@ -131,6 +131,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
   ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)
+  ctx.plugin(uiTui.TuiPromptService)
   ctx.plugin(uiTui, {
     ...config.ui,
     ...config.welcome === undefined ? {} : { welcome: config.welcome },

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -40,7 +40,7 @@ describe('dsh-tui-demo app', () => {
       },
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
-      ui: { color: false, maxToolOutputLines: 3 },
+      ui: { theme: { color: false }, maxToolOutputLines: 3 },
       skills: { tool: { catalogDescriptionMaxLength: 8 } },
       toolBash: { enableRunInBackground: false },
       toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
@@ -55,6 +55,7 @@ describe('dsh-tui-demo app', () => {
       'SessionQuerySqlite',
       'SessionReferenceService',
       'UserInteractionService',
+      'TuiPromptService',
       'ui-tui',
       'agent-spine-demo',
       'tool-ask-user',
@@ -67,15 +68,15 @@ describe('dsh-tui-demo app', () => {
       candidateLimit: 7,
       maxReferenceBytes: 1234,
     })
-    const tuiConfig = calls[7]?.config as { sessionId: string }
+    const tuiConfig = calls[8]?.config as { sessionId: string }
     expect(tuiConfig).toMatchObject({
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
-      color: false,
+      theme: { color: false },
       maxToolOutputLines: 3,
     })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[8]?.config as {
+    const spineConfig = calls[9]?.config as {
       readonly agents: Array<Record<string, unknown>>
       readonly goals: Record<string, never>
       readonly maxParallelToolCalls: number
@@ -111,8 +112,8 @@ describe('dsh-tui-demo app', () => {
     expect(calls[2]?.config).toEqual({ root: './.sessions' })
     expect(calls[5]?.config).toEqual({})
     // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[7]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
+    expect(calls[8]?.config).toEqual({ sessionId: 'persisted-session' })
+    expect((calls[9]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',
       resumeSessionId: 'persisted-session',
     })
@@ -128,12 +129,12 @@ describe('dsh-tui-demo app', () => {
       workspaceContext: false,
     })
 
-    const tuiConfig = calls[6]?.config as { sessionId: string }
+    const tuiConfig = calls[7]?.config as { sessionId: string }
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
+    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
       .toMatchObject({ sessionId: tuiConfig.sessionId })
     expect(calls.map(call => call.name)).not.toContain('command-goal')
-    expect(calls[7]?.config).toMatchObject({ goals: false })
+    expect(calls[8]?.config).toMatchObject({ goals: false })
   })
 
   it('has the namespace-plugin export shape so the Loader keeps its schema', () => {

packages/sdk/helper/src/features/builtin/app.ts

@@ -18,6 +18,7 @@ import {
 } from '../feature.ts'
 import { ProjectContribution, type ProjectResource } from '../resources.ts'
 import {
+  cordisConfigEntry,
   npmCordisConfigEntry,
   optionalString,
   ownedTextFile,
@@ -86,6 +87,10 @@ class AppOption extends FeatureOption {
             id: 'user-interaction',
             name: '@deepseek-ai/dsh-user-interaction',
           }),
+          cordisConfigEntry(ID, {
+            id: 'tui-prompt',
+            name: '@deepseek-ai/dsh-tui/prompt',
+          }),
           ...npmCordisConfigEntry(ID, {
             id: 'tui',
             name: '@deepseek-ai/dsh-tui',

packages/sdk/helper/tests/project.spec.ts

@@ -187,6 +187,7 @@ describe('SdkProject and ProjectEditSession', () => {
     expect(await readFile(join(project.root, 'cordis.yml'), 'utf8'))
       .toContain('sessionId: !!js process.env.DSH_SDK_SESSION_ID')
     expect(project.cordis.entry('tui')?.config).not.toHaveProperty('model')
+    expect(project.cordis.entry('tui-prompt')?.name).toBe('@deepseek-ai/dsh-tui/prompt')
     expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
     expect(project.cordis.entry('session-invariant')?.name).toBe('@deepseek-ai/dsh-session/invariant')
     expect(project.cordis.entry('agent-invariant')?.name).toBe('@deepseek-ai/dsh-agent/invariant')

packages/ui/tui/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 packages/ui/tui/README.md
-README.md: 84ed3de78469ab778118ee5599acfd8476b0ecd1
-README.zh.md: 771b89a91077db7543713b4ce1b5fce0c30c2a16
+README.md: 528daef773635451ceb198ab3231c2dd87cb9413
+README.zh.md: ed19023334389e3f64b8a2f3821307f1540876f2

packages/ui/tui/README.md

@@ -74,7 +74,7 @@ Startup fails before mounting when either process stream is not a TTY. The compo
 
 ## 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; the question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling.
+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, assistant replies, tool cards) are separated by a bold, underlined role header in the role color and blank-line spacing rather than a filled block or a per-line prefix, so a mouse drag-select copies the message text without any leading bar or indent; a tool card's status (pending, error, success) shows in its colored, underlined title glyph and title. The question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling.
 
 ## Model Experience
 

packages/ui/tui/README.zh.md

@@ -74,7 +74,7 @@ Footer 将会话报告的用量汇总为 `↑<uncached input> ↓<output>`；任
 
 ## 颜色
 
-Palette 使用标准 16 色 ANSI 前景色和 SGR 属性，每个终端都会将其重新映射到当前配色方案，因此浅色与深色背景下都保持可读。正文使用终端默认前景色，而非固定色调。成组区域（用户提示词、工具卡片）使用彩色左侧 gutter bar，而非填充背景块；问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。
+Palette 使用标准 16 色 ANSI 前景色和 SGR 属性，每个终端都会将其重新映射到当前配色方案，因此浅色与深色背景下都保持可读。正文使用终端默认前景色，而非固定色调。成组区域（用户提示词、assistant 回复、工具卡片）通过以角色色渲染的粗体带下划线角色标题和空行分隔，而非填充背景块或逐行前缀，因此用鼠标框选复制时不会带上任何左侧竖条或缩进；工具卡片的状态（进行中、错误、成功）由其彩色带下划线的标题字形与标题体现。问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。
 
 ## 模型体验
 

packages/ui/tui/package.json

@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./prompt": {
+      "types": "./lib/types/prompt.d.ts",
+      "default": "./lib/prompt.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/prompt.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -35,9 +40,9 @@
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
     "@deepseek-ai/dsh-goal": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-title": "^0.0.1",
     "@deepseek-ai/dsh-skill": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -59,6 +64,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "0.80.7",
+    "saxes": "6.0.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
@@ -71,9 +77,9 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-reference": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",

packages/ui/tui/src/autocomplete.ts

@@ -0,0 +1,95 @@
+/**
+ * Editor autocomplete provider merging path-only file candidates and optional
+ * session-reference snapshots with the base slash-command completions.
+ * @module @deepseek-ai/dsh-tui/autocomplete
+ */
+
+import {
+  CombinedAutocompleteProvider,
+  type AutocompleteItem,
+  type AutocompleteProvider,
+  type AutocompleteSuggestions,
+} from '@earendil-works/pi-tui'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import {
+  formatSessionReferenceMention,
+  type SessionReferenceService,
+} from '@deepseek-ai/dsh-session-reference'
+import { displayInlineText } from './components/text.ts'
+import { activeAtToken, formatFileMention, WorkspaceFileSearch } from './file-autocomplete.ts'
+
+/** Merge path-only file candidates and optional session snapshots with commands. */
+export class ReferenceAutocompleteProvider implements AutocompleteProvider {
+  constructor(
+    private readonly base: CombinedAutocompleteProvider,
+    private readonly files: WorkspaceFileSearch,
+    private readonly sessions: SessionReferenceService | undefined,
+    private readonly agent: Agent,
+  ) {}
+
+  async getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    options: { signal: AbortSignal; force?: boolean },
+  ): Promise<AutocompleteSuggestions | null> {
+    const basePromise = this.base.getSuggestions(lines, cursorLine, cursorCol, options)
+    const currentLine = lines[cursorLine]
+    /* v8 ignore next -- Editor always supplies its current state line. */
+    if (currentLine === undefined) return basePromise
+    const token = activeAtToken(currentLine, cursorCol)
+    if (token === undefined) {
+      this.files.invalidate()
+      return basePromise
+    }
+    const filePromise = this.files.list(token.query, options.signal).catch(() => [])
+    const sessionPromise = this.sessions === undefined || token.quoted
+      ? Promise.resolve([])
+      : this.sessions.listCandidates(this.agent, token.query, undefined, options.signal).catch(() => [])
+    const [base, fileCandidates, sessionCandidates] = await Promise.all([
+      basePromise,
+      filePromise,
+      sessionPromise,
+    ])
+    if (options.signal.aborted) return base
+    const fileItems: AutocompleteItem[] = fileCandidates.flatMap((candidate) => {
+      const value = formatFileMention(candidate, token.quoted)
+      if (value === undefined) return []
+      const name = candidate.path.slice(candidate.path.lastIndexOf('/') + 1)
+      const directory = candidate.kind === 'directory'
+      return [{
+        value,
+        label: `${directory ? 'Folder' : 'File'} · ${displayInlineText(name)}${directory ? '/' : ''}`,
+        description: displayInlineText(candidate.path),
+      }]
+    })
+    const sessionItems: AutocompleteItem[] = sessionCandidates.map((candidate) => {
+      const mentionLabel = displayInlineText(candidate.label)
+      const sessionId = displayInlineText(candidate.sessionId)
+      const location = candidate.cwd === undefined ? '(no cwd)' : displayInlineText(candidate.cwd)
+      const description = `${candidate.label === candidate.sessionId ? '' : `${sessionId} · `}${location} · ${new Date(candidate.createdAt).toISOString()}`
+      return {
+        value: formatSessionReferenceMention({ sessionId: candidate.sessionId, label: mentionLabel }),
+        label: `Session · ${mentionLabel}`,
+        description,
+      }
+    })
+    const items = [...fileItems, ...sessionItems]
+    if (items.length === 0) return base
+    return { items: [...items, ...(base?.items ?? [])], prefix: token.prefix }
+  }
+
+  applyCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    item: AutocompleteItem,
+    prefix: string,
+  ): { lines: string[]; cursorLine: number; cursorCol: number } {
+    return this.base.applyCompletion(lines, cursorLine, cursorCol, item, prefix)
+  }
+
+  shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number): boolean {
+    return this.base.shouldTriggerFileCompletion(lines, cursorLine, cursorCol)
+  }
+}

packages/ui/tui/src/components/content.ts

@@ -0,0 +1,56 @@
+/**
+ * Content-block primitives shared across the terminal front door: flattening
+ * session content to display text and parsing tool-call arguments.
+ * @module @deepseek-ai/dsh-tui/components/content
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+
+/**
+ * Flatten content blocks into a single display string, recursing into
+ * tool-result content and naming unknown block types.
+ * @param content - Content blocks to flatten.
+ * @returns The concatenated display text.
+ */
+export 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('')
+}
+
+/** A tool call's arguments parsed from their JSON source, with a validity flag. */
+export interface ParsedArguments {
+  value: unknown
+  valid: boolean
+}
+
+/**
+ * Parse tool-call arguments from their JSON source.
+ * @param raw - Raw JSON arguments text.
+ * @returns The parsed value, or the raw text with `valid: false` on parse failure.
+ */
+export function parseArguments(raw: string): ParsedArguments {
+  try {
+    return { value: JSON.parse(raw), valid: true }
+  } catch {
+    return { value: raw, valid: false }
+  }
+}

packages/ui/tui/src/components/dialogs.ts

@@ -0,0 +1,790 @@
+/**
+ * pi-tui dialog and selector components for the terminal front door: the status
+ * card, prompt-context line, model selector, resume picker, and user-question
+ * dialog, plus the model-choice and resume-candidate data they present.
+ * @module @deepseek-ai/dsh-tui/components/dialogs
+ */
+
+import {
+  Input,
+  Key,
+  SelectList,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Component,
+  type Focusable,
+  type SelectItem,
+} from '@earendil-works/pi-tui'
+import type { Context } from 'cordis'
+import {
+  type Agent,
+  type AgentLlmTarget,
+} from '@deepseek-ai/dsh-agent'
+import type { LlmModelInfo, LlmModelReasoningInfo, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import { foldGoal, type GoalPhase } from '@deepseek-ai/dsh-goal'
+import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+import type {
+  SessionLogSnapshot,
+  SessionRecord,
+} from '@deepseek-ai/dsh-session-query'
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction'
+import { BRACKETED_PASTE_END, BRACKETED_PASTE_START, displayText, sanitizePastedText } from './text.ts'
+import { dialogSelectTheme, type Palette } from './theme.ts'
+import {
+  renderTuiPromptTemplate,
+  type TuiPromptTemplateToken,
+} from '../prompt.ts'
+
+/** A selectable model advertised by a provider, with its display name, description, and reasoning metadata. */
+export interface ModelChoice extends AgentLlmTarget {
+  modelName: string
+  description?: string
+  reasoning?: LlmModelReasoningInfo
+}
+
+/**
+ * The provider/model route and selected reasoning effort resolved from a model dialog.
+ */
+export interface ModelDialogSelection {
+  choice: ModelChoice
+  reasoningEffort: ReasoningEffortId | undefined
+}
+
+/**
+ * Format a provider/model target as its `provider/model` label.
+ * @param target - The LLM target.
+ * @returns The `provider/model` label.
+ */
+export function targetLabel(target: AgentLlmTarget): string {
+  return `${target.provider}/${target.model}`
+}
+
+/**
+ * Format a target compactly as its model name with any selected reasoning effort appended.
+ * @param target - The LLM target.
+ * @returns The compact `model [effort]` label.
+ */
+export function compactTargetLabel(target: AgentLlmTarget): string {
+  return `${target.model}${target.reasoningEffort === undefined ? '' : ` ${target.reasoningEffort}`}`
+}
+
+/**
+ * Resolve the display label for a choice's reasoning effort.
+ * @param choice - The model choice carrying advertised reasoning metadata.
+ * @param effort - The selected effort, or `undefined` for provider default.
+ * @returns The effort's display name, `provider default`, or `undefined` when the model has no reasoning metadata.
+ */
+export function targetReasoningLabel(choice: ModelChoice, effort: ReasoningEffortId | undefined): string | undefined {
+  if (effort === undefined) return choice.reasoning === undefined ? undefined : 'provider default'
+  return choice.reasoning?.efforts.find(candidate => candidate.id === effort)?.name ?? effort
+}
+
+/**
+ * Derive the agent's initial LLM target from its logged request header or options.
+ * @param agent - The driven agent.
+ * @returns The initial target, or `undefined` when unset.
+ */
+export function initialTarget(agent: Agent): AgentLlmTarget | undefined {
+  const logged = agent.session.requestHeader()?.config
+  if (logged !== undefined) {
+    if (logged.reasoningEffort === undefined) {
+      return { provider: logged.provider, model: logged.model }
+    }
+    return { provider: logged.provider, model: logged.model, reasoningEffort: logged.reasoningEffort }
+  }
+  if (agent.options.provider === undefined || agent.options.model === undefined) return undefined
+  return { provider: agent.options.provider, model: agent.options.model }
+}
+
+/**
+ * List every advertised model across registered providers, appending the current
+ * target when a provider does not advertise it.
+ * @param ctx - Context supplying the LLM service.
+ * @param current - The current target, appended when unadvertised.
+ * @returns The model choices, flattened across providers.
+ */
+export async function readModelChoices(
+  ctx: Context,
+  current: AgentLlmTarget | undefined,
+): Promise<ModelChoice[]> {
+  const providers = ctx.llm.listProviders()
+  const groups = await Promise.all(providers.map(async (provider) => {
+    const advertised = await ctx.llm.listModels(provider.id)
+    const models: LlmModelInfo[] = [...advertised]
+    if (
+      current?.provider === provider.id
+      && !models.some(model => model.id === current.model)
+    ) {
+      models.push({ provider: provider.id, id: current.model, name: current.model })
+    }
+    return Promise.all(models.map(async (model): Promise<ModelChoice> => {
+      const reasoning = (await ctx.llm.resolveModelInfo(provider.id, model.id)).reasoning
+      return {
+        provider: provider.id,
+        model: model.id,
+        modelName: model.name,
+        ...model.description === undefined ? {} : { description: model.description },
+        ...reasoning === undefined ? {} : { reasoning },
+      }
+    }))
+  }))
+  return groups.flat()
+}
+
+/**
+ * Format a diagnostic integer with grouping separators.
+ * @param value - Integer to format.
+ * @returns The grouped decimal string.
+ */
+export function formatDiagnosticNumber(value: number): string {
+  return value.toLocaleString('en-US')
+}
+
+/**
+ * Format a diagnostic timestamp as an ISO date-time in UTC.
+ * @param value - Epoch milliseconds.
+ * @returns The formatted UTC timestamp.
+ */
+export function formatDiagnosticTime(value: number): string {
+  return new Date(value).toISOString().replace('T', ' ').replace(/\.\d{3}Z$/u, ' UTC')
+}
+
+/**
+ * Format a pluralized count for a diagnostic row.
+ * @param value - Count.
+ * @param singular - Singular noun; an `s` is appended for other counts.
+ * @returns The formatted count.
+ */
+export function formatDiagnosticCount(value: number, singular: string): string {
+  return `${String(value)} ${singular}${value === 1 ? '' : 's'}`
+}
+
+/**
+ * Render a fixed-width filled meter bar for a percentage.
+ * @param percent - Percentage in [0, 100].
+ * @param palette - Active role palette.
+ * @returns The rendered meter.
+ */
+export function diagnosticMeter(percent: number, palette: Palette): string {
+  const width = 16
+  const filled = Math.round(Math.min(100, Math.max(0, percent)) / 100 * width)
+  return `${palette.dim('[')}${palette.accent('█'.repeat(filled))}${palette.dim(`${'░'.repeat(width - filled)}]`)}`
+}
+
+/** One `label: value` row of a status card group. */
+export type StatusCardRow = readonly [label: string, value: string]
+
+/** Bordered, grouped field card for one point-in-time status snapshot. */
+export class StatusCardComponent implements Component {
+  constructor(
+    private readonly groups: readonly (readonly StatusCardRow[])[],
+    private readonly palette: Palette,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const labels = this.groups.flatMap(group => group.map(([label]) => `${label}:`))
+    const naturalLabelWidth = Math.max(...labels.map(label => label.length))
+    const naturalBodyWidth = Math.max(...this.groups.flatMap(group => group.map(([, value]) =>
+      1 + naturalLabelWidth + 2 + visibleWidth(value))))
+    const cardWidth = Math.min(
+      Math.max(8, width),
+      Math.max('Session status'.length + 5, naturalBodyWidth + 4),
+    )
+    const innerWidth = Math.max(1, cardWidth - 4)
+    const labelWidth = Math.min(
+      naturalLabelWidth,
+      Math.max(1, Math.floor(innerWidth / 3)),
+    )
+    const body: string[] = []
+    for (const [groupIndex, group] of this.groups.entries()) {
+      if (groupIndex > 0) body.push('')
+      for (const [label, value] of group) {
+        const plainLabel = truncateToWidth(`${label}:`, labelWidth, '')
+        const prefix = ` ${this.palette.muted(plainLabel.padEnd(labelWidth))}  `
+        const continuation = ' '.repeat(1 + labelWidth + 2)
+        const valueWidth = Math.max(1, innerWidth - visibleWidth(prefix))
+        const wrapped = wrapTextWithAnsi(value, valueWidth)
+        for (const [lineIndex, line] of wrapped.entries()) {
+          body.push(`${lineIndex === 0 ? prefix : continuation}${line}`)
+        }
+      }
+    }
+
+    const title = truncateToWidth('Session status', Math.max(1, cardWidth - 5), '')
+    const topTail = '─'.repeat(Math.max(0, cardWidth - visibleWidth(title) - 5))
+    const top = `${this.palette.dim('╭─ ')}${this.palette.bold(this.palette.accent(title))}${this.palette.dim(` ${topTail}╮`)}`
+    const lines = [top]
+    for (const line of body) {
+      const clipped = truncateToWidth(line, innerWidth, '')
+      lines.push(`${this.palette.dim('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${this.palette.dim('│')}`)
+    }
+    lines.push(this.palette.dim(`╰${'─'.repeat(Math.max(0, cardWidth - 2))}╯`))
+    return lines
+  }
+}
+
+/** The left/right template line rendered above the editor. */
+export class PromptContextComponent implements Component {
+  constructor(
+    private readonly leftTemplate: readonly TuiPromptTemplateToken[],
+    private readonly rightTemplate: readonly TuiPromptTemplateToken[],
+    private readonly resolve: (name: string) => string | undefined,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const right = truncateToWidth(renderTuiPromptTemplate(this.rightTemplate, this.resolve), width, '')
+    const rightWidth = visibleWidth(right)
+    const leftCapacity = Math.max(0, width - rightWidth - (rightWidth === 0 ? 0 : 2))
+    const left = truncateToWidth(renderTuiPromptTemplate(this.leftTemplate, this.resolve), leftCapacity, '')
+    if (rightWidth === 0) return [left]
+    const gap = ' '.repeat(Math.max(0, width - visibleWidth(left) - rightWidth))
+    return [`${left}${gap}${right}`]
+  }
+}
+
+/** A user's answer to one question: chosen option labels and an optional custom answer. */
+export interface QuestionSelection {
+  selected: string[]
+  custom?: string
+}
+
+/**
+ * Render a bordered dialog frame around body lines with a titled top edge.
+ * @param title - Dialog title shown in the top border.
+ * @param body - Body lines.
+ * @param width - Dialog width in columns.
+ * @param palette - Active role palette.
+ * @returns The framed dialog lines.
+ */
+export function renderDialog(
+  title: string,
+  body: readonly string[],
+  width: number,
+  palette: Palette,
+): string[] {
+  const innerWidth = Math.max(1, width - 4)
+  const topLabel = ` ${displayText(title)} `
+  const top = `╭${topLabel}${'─'.repeat(Math.max(0, width - visibleWidth(topLabel) - 2))}╮`
+  const lines: string[] = [palette.accent(top)]
+  for (const line of body) {
+    const clipped = truncateToWidth(line, innerWidth, '')
+    lines.push(`${palette.accent('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${palette.accent('│')}`)
+  }
+  lines.push(palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`))
+  return lines
+}
+
+/** Keyboard model selector rendered as a bordered overlay, with per-model reasoning-effort cycling. */
+export class ModelDialog implements Component {
+  private readonly list: SelectList
+  private readonly items: Map<string, SelectItem>
+  private readonly choices: Map<string, ModelChoice>
+  private readonly efforts: Map<string, ReasoningEffortId | undefined>
+  private readonly currentValue: string | undefined
+
+  constructor(
+    choices: readonly ModelChoice[],
+    current: AgentLlmTarget | undefined,
+    maxVisible: number,
+    private readonly palette: Palette,
+    done: (selection: ModelDialogSelection) => void,
+    cancel: () => void,
+  ) {
+    this.items = new Map()
+    this.choices = new Map()
+    this.efforts = new Map()
+    this.currentValue = current === undefined ? undefined : targetLabel(current)
+    for (const choice of choices) {
+      const value = targetLabel(choice)
+      const isCurrent = current?.provider === choice.provider && current.model === choice.model
+      this.choices.set(value, choice)
+      this.efforts.set(
+        value,
+        isCurrent
+          ? current.reasoningEffort ?? choice.reasoning?.defaultEffort
+          : choice.reasoning?.defaultEffort,
+      )
+      this.items.set(value, {
+        value,
+        label: displayText(value),
+        description: this.describeChoice(choice, isCurrent),
+      })
+    }
+    this.list = new SelectList([...this.items.values()], maxVisible, dialogSelectTheme(palette))
+    const currentIndex = current === undefined
+      ? 0
+      : choices.findIndex(choice => choice.provider === current.provider && choice.model === current.model)
+    this.list.setSelectedIndex(currentIndex)
+    this.list.onSelect = (item) => {
+      const selected = choices.find(choice => targetLabel(choice) === item.value)
+      /* v8 ignore next -- SelectList only returns values built from `choices`. */
+      if (selected === undefined) return
+      done({ choice: selected, reasoningEffort: this.efforts.get(item.value) })
+    }
+    this.list.onCancel = cancel
+  }
+
+  private describeChoice(choice: ModelChoice, isCurrent: boolean): string {
+    const effortLabel = targetReasoningLabel(choice, this.efforts.get(targetLabel(choice)))
+    return [
+      displayText(choice.modelName),
+      ...choice.description === undefined ? [] : [displayText(choice.description)],
+      ...effortLabel === undefined ? [] : [displayText(effortLabel)],
+      ...isCurrent ? ['current'] : [],
+    ].join(' — ')
+  }
+
+  private cycleReasoningEffort(): void {
+    const selectedItem = this.list.getSelectedItem()
+    /* v8 ignore next -- the dialog is opened only for a non-empty catalog. */
+    if (selectedItem === null) return
+    const choice = this.choices.get(selectedItem.value)
+    if (choice?.reasoning === undefined) return
+    const current = this.efforts.get(selectedItem.value)
+    const efforts: Array<ReasoningEffortId | undefined> = [
+      ...choice.reasoning.defaultEffort === undefined ? [undefined] : [],
+      ...choice.reasoning.efforts.map(effort => effort.id),
+    ]
+    const currentIndex = efforts.indexOf(current)
+    const next = efforts[(currentIndex + 1) % efforts.length]
+    this.efforts.set(selectedItem.value, next)
+    const item = this.items.get(selectedItem.value)
+    /* v8 ignore next -- items and choices are constructed from the same values. */
+    if (item === undefined) return
+    item.description = this.describeChoice(choice, selectedItem.value === this.currentValue)
+  }
+
+  invalidate(): void {
+    this.list.invalidate()
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.shift(Key.tab))) {
+      this.cycleReasoningEffort()
+    } else {
+      this.list.handleInput(data)
+    }
+    this.invalidate()
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 4)
+    return renderDialog('Select model', [
+      ...this.list.render(innerWidth),
+      '',
+      this.palette.dim('↑/↓ navigate • Shift+Tab reasoning • Enter select • Esc cancel'),
+    ], width, this.palette)
+  }
+}
+
+/** The provider/model route recovered from a resume candidate's log. */
+export interface ResumeRoute {
+  provider: string
+  model: string
+}
+
+/** A preflighted resume selector row summarizing one persisted session. */
+export interface ResumeCandidate {
+  record: SessionRecord
+  title: string
+  lastActivityAt: number
+  lastTurn: string
+  route?: ResumeRoute
+  goalPhase?: GoalPhase
+  disabledReason?: string
+}
+
+function resumeTurnLabel(snapshot: SessionLogSnapshot): string {
+  const event = snapshot.events.findLast(item => item.type === 'turn/end')
+  if (event === undefined) return 'no completed turn'
+  const reason = event.data.reason
+  switch (reason.kind) {
+    case 'completed': return `turn ${event.data.turn}: completed`
+    case 'aborted': return `turn ${event.data.turn}: cancelled`
+    case 'error': return `turn ${event.data.turn}: error`
+    case 'disposed': return `turn ${event.data.turn}: disposed`
+    case 'max-tokens': return `turn ${event.data.turn}: max tokens`
+    case 'rejected': return `turn ${event.data.turn}: rejected`
+    case 'interrupted': return `turn ${event.data.turn}: interrupted`
+    default: return `turn ${event.data.turn}: unknown result`
+  }
+}
+
+function resumeRoute(snapshot: SessionLogSnapshot): ResumeRoute | undefined {
+  const header = snapshot.events.findLast(item => item.type === 'request/header')
+  if (header?.type === 'request/header') {
+    return { provider: header.data.header.config.provider, model: header.data.header.config.model }
+  }
+  const assistant = snapshot.events.findLast(item => item.type === 'assistant/message')
+  return assistant?.type === 'assistant/message'
+    ? { provider: assistant.data.provenance.provider, model: assistant.data.provenance.model }
+    : undefined
+}
+
+/**
+ * Build one resume selector row from a record and its log snapshot, deriving the
+ * title, route, goal phase, and any reason the session cannot be resumed here.
+ * @param record - The session record.
+ * @param snapshot - The session's log snapshot.
+ * @param currentId - The current session id.
+ * @param cwd - The current workspace directory.
+ * @param availableProviders - Providers registered in this runtime.
+ * @returns The summarized resume candidate.
+ */
+export function summarizeResumeCandidate(
+  record: SessionRecord,
+  snapshot: SessionLogSnapshot,
+  currentId: SessionId,
+  cwd: string | undefined,
+  availableProviders: ReadonlySet<string>,
+): ResumeCandidate {
+  const title = foldSessionTitle(snapshot.events)?.title ?? 'Untitled session'
+  const route = resumeRoute(snapshot)
+  const foldedGoal = foldGoal(snapshot.events).goal
+  let disabledReason: string | undefined
+  if (record.header.id === currentId) disabledReason = 'current session'
+  else if (record.live) disabledReason = 'session is already live in this runtime'
+  else if (record.header.cwd !== cwd) disabledReason = 'different workspace'
+  else if (route !== undefined && !availableProviders.has(route.provider)) {
+    disabledReason = `session is complete, but route is currently unavailable (${route.provider}/${route.model})`
+  }
+  return {
+    record,
+    title,
+    lastActivityAt: snapshot.events.at(-1)?.time ?? snapshot.session.createdAt,
+    lastTurn: resumeTurnLabel(snapshot),
+    ...route === undefined ? {} : { route },
+    /* v8 ignore next -- goal-bearing resume records are covered by the goal/session integration surface. */
+    ...foldedGoal === undefined ? {} : { goalPhase: foldedGoal.phase },
+    ...disabledReason === undefined ? {} : { disabledReason },
+  }
+}
+
+/** Full-viewport keyboard selector over detached, preflighted resume summaries. */
+export class ResumePicker implements Component, Focusable {
+  private readonly search = new Input()
+  private pasteBuffer: string | undefined
+  private selectedIndex = 0
+  private error = ''
+  focused = false
+
+  constructor(
+    private readonly candidates: readonly ResumeCandidate[],
+    private readonly maxVisible: number,
+    private readonly workspaceLabel: string,
+    private readonly viewportRows: () => number,
+    private readonly palette: Palette,
+    private readonly done: (candidate: ResumeCandidate) => void,
+    private readonly cancel: () => void,
+  ) {}
+
+  invalidate(): void {
+    this.search.invalidate()
+  }
+
+  private filtered(): ResumeCandidate[] {
+    const query = this.search.getValue().trim().toLocaleLowerCase()
+    if (query === '') return [...this.candidates]
+    return this.candidates.filter(candidate => candidate.title.toLocaleLowerCase().includes(query)
+      || candidate.record.header.id.toLocaleLowerCase().includes(query))
+  }
+
+  private visibleCandidateCount(): number {
+    const candidateBudget = Math.max(1, Math.floor((Math.max(1, this.viewportRows()) - 13) / 4))
+    return Math.min(this.maxVisible, candidateBudget)
+  }
+
+  private handleBracketedPaste(data: string): boolean {
+    const start = data.indexOf(BRACKETED_PASTE_START)
+    if (this.pasteBuffer === undefined && start < 0) return false
+    if (this.pasteBuffer === undefined) {
+      const prefix = data.slice(0, start)
+      if (prefix !== '') this.handleInput(prefix)
+      this.pasteBuffer = data.slice(start + BRACKETED_PASTE_START.length)
+    } else {
+      this.pasteBuffer += data
+    }
+    const end = this.pasteBuffer.indexOf(BRACKETED_PASTE_END)
+    if (end < 0) return true
+    const pasted = sanitizePastedText(this.pasteBuffer.slice(0, end))
+    const remaining = this.pasteBuffer.slice(end + BRACKETED_PASTE_END.length)
+    this.pasteBuffer = undefined
+    const previous = this.search.getValue()
+    this.search.handleInput(`${BRACKETED_PASTE_START}${pasted}${BRACKETED_PASTE_END}`)
+    if (this.search.getValue() !== previous) {
+      this.selectedIndex = 0
+      this.error = ''
+    }
+    if (remaining !== '') this.handleInput(remaining)
+    this.invalidate()
+    return true
+  }
+
+  handleInput(data: string): void {
+    if (this.handleBracketedPaste(data)) return
+    const filtered = this.filtered()
+    if (matchesKey(data, Key.ctrl('c'))) {
+      this.cancel()
+      return
+    }
+    if (matchesKey(data, Key.escape)) {
+      if (this.search.getValue() === '') this.cancel()
+      else {
+        this.search.setValue('')
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    } else if (matchesKey(data, Key.up)) {
+      this.selectedIndex = filtered.length === 0
+        ? 0
+        : (this.selectedIndex + filtered.length - 1) % filtered.length
+    } else if (matchesKey(data, Key.down)) {
+      this.selectedIndex = filtered.length === 0 ? 0 : (this.selectedIndex + 1) % filtered.length
+    } else if (matchesKey(data, Key.pageUp)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - this.visibleCandidateCount())
+    } else if (matchesKey(data, Key.pageDown)) {
+      this.selectedIndex = Math.min(
+        Math.max(0, filtered.length - 1),
+        this.selectedIndex + this.visibleCandidateCount(),
+      )
+    } else if (matchesKey(data, Key.enter)) {
+      const selected = filtered[this.selectedIndex]
+      if (selected === undefined) this.error = 'No session matches this search.'
+      else if (selected.disabledReason !== undefined) this.error = selected.disabledReason
+      else this.done(selected)
+    } else {
+      const previous = this.search.getValue()
+      this.search.focused = this.focused
+      this.search.handleInput(data)
+      if (this.search.getValue() !== previous) {
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    }
+    this.invalidate()
+  }
+
+  render(width: number): string[] {
+    this.search.focused = this.focused
+    const height = Math.max(1, this.viewportRows())
+    const horizontalPadding = width >= 12 ? 2 : 0
+    const contentWidth = Math.max(1, width - horizontalPadding * 2)
+    const indent = ' '.repeat(horizontalPadding)
+    const filtered = this.filtered()
+    if (this.selectedIndex >= filtered.length) this.selectedIndex = Math.max(0, filtered.length - 1)
+    const selected = filtered[this.selectedIndex]
+    const position = selected === undefined ? 0 : this.selectedIndex + 1
+    const lines: string[] = [
+      '',
+      `${indent}${this.palette.bold(this.palette.accent(`Resume session (${position} of ${filtered.length})`))}`,
+      '',
+    ]
+
+    const searchInnerWidth = Math.max(1, contentWidth - 4)
+    lines.push(`${indent}${this.palette.dim(`╭${'─'.repeat(Math.max(0, contentWidth - 2))}╮`)}`)
+    const searchContent = this.search.render(searchInnerWidth).join('').replace(/^> /u, '⌕ ')
+    const clippedSearch = truncateToWidth(searchContent, searchInnerWidth, '')
+    lines.push(
+      `${indent}${this.palette.dim('│')} ${clippedSearch}${' '.repeat(Math.max(0, searchInnerWidth - visibleWidth(clippedSearch)))} ${this.palette.dim('│')}`,
+      `${indent}${this.palette.dim(`╰${'─'.repeat(Math.max(0, contentWidth - 2))}╯`)}`,
+      '',
+      `${indent}${this.palette.muted(displayText(this.workspaceLabel))}`,
+      '',
+    )
+
+    const visibleCount = this.visibleCandidateCount()
+    const start = Math.max(0, Math.min(
+      this.selectedIndex - Math.floor(visibleCount / 2),
+      filtered.length - visibleCount,
+    ))
+    const end = Math.min(filtered.length, start + visibleCount)
+    const push = (line: string): void => {
+      lines.push(`${indent}${truncateToWidth(line, contentWidth, '…')}`)
+    }
+    for (let index = start; index < end; index += 1) {
+      const candidate = filtered[index] as ResumeCandidate
+      const active = index === this.selectedIndex
+      const status = [
+        candidate.disabledReason === 'current session' ? 'current' : undefined,
+        candidate.record.live ? 'live' : undefined,
+        candidate.record.persisted ? 'persisted' : undefined,
+      ].filter((value): value is string => value !== undefined).join(' · ')
+      const lead = `${active ? '❯' : ' '} ${displayText(candidate.title)}`
+      push(active ? this.palette.bold(this.palette.accent(lead)) : lead)
+      const route = candidate.route === undefined ? 'route unavailable' : `${candidate.route.provider}/${candidate.route.model}`
+      /* v8 ignore next -- only goal-bearing resume records add this integration-owned suffix. */
+      const goal = candidate.goalPhase === undefined ? '' : ` · goal ${candidate.goalPhase}`
+      push(this.palette.muted(`  ${new Date(candidate.lastActivityAt).toISOString()} · ${candidate.lastTurn} · ${route}${goal}`))
+      push(this.palette.dim(`  ${status} · ${displayText(candidate.record.header.id)}`))
+      if (candidate.disabledReason !== undefined) {
+        push(this.palette.warning(`  unavailable: ${displayText(candidate.disabledReason)}`))
+      }
+    }
+    if (filtered.length === 0) push(this.palette.warning('No matching sessions.'))
+    if (this.error !== '') {
+      lines.push('')
+      push(this.palette.error(displayText(this.error)))
+    }
+
+    const footer = `${indent}${this.palette.dim('Type to search  •  ↑/↓ navigate  •  Enter resume  •  Esc clear/cancel')}`
+    while (lines.length < height - 2) lines.push('')
+    lines.push(footer, '')
+    return lines.slice(0, height)
+  }
+}
+
+/** Bottom-anchored dialog for one user question with option or custom-answer modes. */
+export 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 position: number,
+    private readonly total: number,
+    private readonly unanswered: number,
+    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 Tab for a custom answer.'
+        return
+      }
+      this.done({ selected: indices.map(index => options[index]?.label).filter((label): label is string => label !== undefined) })
+    } else if (matchesKey(data, Key.tab) || 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 header = `Question ${this.position}/${this.total} (${this.unanswered} unanswered)${this.question.header === undefined ? '' : ` · ${displayText(this.question.header)}`}`
+    const lines = [
+      this.palette.muted(header),
+      ...wrapTextWithAnsi(this.palette.text(displayText(this.question.question)), innerWidth),
+    ]
+    const push = (line: string): void => { lines.push(line) }
+    // Supporting detail (e.g. the full plan under review) renders between the
+    // question and the answer surface, kept out of option labels.
+    if (this.question.detail !== undefined) {
+      push('')
+      for (const line of wrapTextWithAnsi(displayText(this.question.detail), 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)
+      const optionRows = options.slice(start, end).map((option, offset) => {
+        const index = start + offset
+        const mark = this.question.multiSelect
+          ? this.selected.has(index) ? '[x] ' : '[ ] '
+          : ''
+        return `${index === this.selectedIndex ? '›' : ' '} ${index + 1}. ${mark}${displayText(option.label)}`
+      })
+      const descriptionColumn = Math.min(
+        Math.max(...optionRows.map(row => visibleWidth(row))) + 2,
+        Math.max(1, Math.floor(innerWidth * 0.55)),
+      )
+      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 mark = this.question.multiSelect
+          ? this.selected.has(index) ? '[x] ' : '[ ] '
+          : ''
+        const left = `${index === this.selectedIndex ? '›' : ' '} ${index + 1}. ${mark}${displayText(option.label)}`
+        const leftStyled = index === this.selectedIndex
+          ? this.palette.bold(this.palette.accent(left))
+          : left
+        const description = option.description === undefined
+          ? ''
+          : `${' '.repeat(Math.max(1, descriptionColumn - visibleWidth(left)))}${this.palette.muted(displayText(option.description))}`
+        push(`${leftStyled}${description}`)
+      }
+      if (options.length > this.maxVisible) push(this.palette.dim(`${this.selectedIndex + 1}/${options.length}`))
+      const controls = [
+        'Tab custom answer',
+        ...(options.length > 1 ? ['↑/↓ navigate'] : []),
+        ...(this.question.multiSelect ? ['Space toggle'] : []),
+        'Enter submit',
+        'Esc interrupt',
+      ]
+      const hint = this.palette.dim(controls.join(' • '))
+      for (const line of wrapTextWithAnsi(hint, innerWidth)) push(line)
+    }
+    if (this.error) {
+      for (const line of wrapTextWithAnsi(this.palette.error(this.error), innerWidth)) push(line)
+    }
+    return ['', ...lines, ''].map((line) => {
+      const clipped = truncateToWidth(line, innerWidth, '')
+      return `  ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))}  `
+    })
+  }
+}

packages/ui/tui/src/components/text.ts

@@ -0,0 +1,49 @@
+/**
+ * Terminal text sanitization shared across the pi-tui front door. External text
+ * (model output, tool results, clipboard) is escaped or stripped of C0/C1
+ * controls before the TUI adds its own application-owned ANSI.
+ * @module @deepseek-ai/dsh-tui/components/text
+ */
+
+const TERMINAL_CONTROL_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/gu
+const TERMINAL_OSC_PATTERN = /(?:\u001B\]|\u009D)(?:(?!\u0007|\u001B\\)[\s\S])*(?:\u0007|\u001B\\|$)/gu
+const TERMINAL_CSI_PATTERN = /(?:\u001B\[|\u009B)[0-?]*[ -/]*[@-~]/gu
+const TERMINAL_ESCAPE_PATTERN = /\u001B[@-_]/gu
+
+/** Bracketed-paste start marker emitted by terminals around pasted content. */
+export const BRACKETED_PASTE_START = '\u001B[200~'
+/** Bracketed-paste end marker emitted by terminals around pasted content. */
+export const BRACKETED_PASTE_END = '\u001B[201~'
+
+/**
+ * Escape external C0/C1 controls before pi-tui adds application-owned ANSI.
+ * Line feeds remain structural so transcript and tool output retain their layout.
+ * @param text - Untrusted text to render.
+ * @returns The text with control characters escaped as `\xNN`.
+ */
+export function displayText(text: string): string {
+  return text.replace(TERMINAL_CONTROL_PATTERN, control =>
+    `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`)
+}
+
+/**
+ * Escape external controls for terminal fields that must remain on one line.
+ * @param text - Untrusted text to render inline.
+ * @returns The escaped text with newlines rendered as `\x0a`.
+ */
+export function displayInlineText(text: string): string {
+  return displayText(text).replaceAll('\n', '\\x0a')
+}
+
+/**
+ * Remove terminal controls from clipboard text before an editable field stores it.
+ * @param text - Raw pasted clipboard text.
+ * @returns The text stripped of OSC, CSI, escape, and control sequences.
+ */
+export function sanitizePastedText(text: string): string {
+  return text
+    .replace(TERMINAL_OSC_PATTERN, '')
+    .replace(TERMINAL_CSI_PATTERN, '')
+    .replace(TERMINAL_ESCAPE_PATTERN, '')
+    .replace(TERMINAL_CONTROL_PATTERN, '')
+}

packages/ui/tui/src/components/theme.ts

@@ -0,0 +1,184 @@
+/**
+ * Theme-agnostic ANSI palette and derived pi-tui themes for the terminal front
+ * door. The palette is built from the standard 16-color ANSI set plus SGR
+ * attributes so every terminal remaps it to its active color scheme.
+ * @module @deepseek-ai/dsh-tui/components/theme
+ */
+
+import type {
+  MarkdownTheme,
+  SelectListTheme,
+  TerminalColorScheme,
+} from '@earendil-works/pi-tui'
+
+/** Theme-agnostic role colors and SGR attribute wrappers. */
+export 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
+}
+
+/**
+ * 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 bold, underlined role
+ * headers and reverse video rather than fixed background fills or per-line
+ * prefixes, so a transcript drag-select copies message text without stray
+ * glyphs.
+ *
+ * @param enabled - Whether ANSI is emitted at all.
+ * @param scheme - Active terminal color scheme; adjusts dim and code roles.
+ * @returns The role palette for the given scheme.
+ */
+export function createPalette(enabled: boolean, scheme: TerminalColorScheme = 'dark'): Palette {
+  return {
+    accent: ansi('94', '39', enabled),
+    accent2: ansi('95', '39', enabled),
+    text: text => text,
+    muted: ansi('90', '39', enabled),
+    // SGR 2 (dim) lightens text on a light background — substitute ANSI 90
+    // (bright black / gray) which renders as a readable muted tone on any scheme.
+    dim: scheme === 'light' ? ansi('90', '39', enabled) : ansi('2', '22', enabled),
+    success: ansi('32', '39', enabled),
+    warning: ansi('33', '39', enabled),
+    error: ansi('31', '39', enabled),
+    // ANSI 36 (cyan) is difficult to read on a light background — use
+    // ANSI 34 (blue) which is legible on both light and dark schemes.
+    code: scheme === 'light' ? ansi('34', '39', enabled) : 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),
+  }
+}
+
+/**
+ * DeepSeek brand gradient stops (indigo → light blue) taken from the
+ * deepseek.com logo, painted across the startup banner's product name on
+ * truecolor terminals. Fixed brand identity, deliberately outside the
+ * theme-adaptive {@link Palette}.
+ */
+const BRAND_GRADIENT = [
+  [77, 107, 254], // #4D6BFE
+  [57, 130, 255], // #3982FF
+  [36, 152, 255], // #2498FF
+] as const
+
+/**
+ * Sample {@link BRAND_GRADIENT} at fraction `t` via piecewise-linear
+ * interpolation across its stops.
+ *
+ * @param t - Position along the gradient; clamped to [0, 1].
+ * @returns The interpolated `[r, g, b]` channels, each rounded to 0–255.
+ */
+function brandColorAt(t: number): readonly [number, number, number] {
+  const span = Math.min(Math.max(t, 0), 1) * (BRAND_GRADIENT.length - 1)
+  const index = Math.min(Math.floor(span), BRAND_GRADIENT.length - 2)
+  const local = span - index
+  // `index` is clamped to a valid adjacent pair, so both lookups are in-bounds.
+  const from = BRAND_GRADIENT[index] as readonly [number, number, number]
+  const to = BRAND_GRADIENT[index + 1] as readonly [number, number, number]
+  return [
+    Math.round(from[0] + (to[0] - from[0]) * local),
+    Math.round(from[1] + (to[1] - from[1]) * local),
+    Math.round(from[2] + (to[2] - from[2]) * local),
+  ]
+}
+
+/**
+ * Paint `text` left-to-right in the DeepSeek brand gradient with per-character
+ * 24-bit foreground codes, resetting to the default foreground at the end.
+ * Foreground-only, so it stays legible on any terminal background; the caller
+ * gates it on truecolor support and wraps it in bold.
+ *
+ * @param text - Text to colorize; sampled once per character.
+ * @returns `text` wrapped in truecolor SGR foreground codes.
+ */
+export function gradientText(text: string): string {
+  // The sole caller passes the ASCII product name, so UTF-16 unit iteration
+  // samples exactly one color per visible letter.
+  const last = Math.max(1, text.length - 1)
+  let painted = ''
+  for (let index = 0; index < text.length; index += 1) {
+    const [r, g, b] = brandColorAt(index / last)
+    painted += `\x1b[38;2;${r};${g};${b}m${text.charAt(index)}`
+  }
+  return `${painted}\x1b[39m`
+}
+
+/**
+ * Derive the pi-tui Markdown theme from a role palette.
+ * @param palette - Active role palette.
+ * @returns The Markdown theme wired to palette roles.
+ */
+export 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.code(text),
+    // pi-tui presents both fence rows through this callback. Keep the opening
+    // language label, but hide Markdown syntax and the otherwise-empty close.
+    codeBlockBorder: text => palette.dim(text.slice(3)),
+    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),
+  }
+}
+
+/**
+ * Derive the pi-tui select-list theme from a role palette.
+ * @param palette - Active role palette.
+ * @returns The select-list theme wired to palette roles.
+ */
+export function selectTheme(palette: Palette): SelectListTheme {
+  return {
+    selectedPrefix: palette.accent,
+    selectedText: palette.accent,
+    description: palette.muted,
+    scrollInfo: palette.dim,
+    noMatch: palette.warning,
+  }
+}
+
+/**
+ * Derive the reverse-video dialog select-list theme from a role palette.
+ * @param palette - Active role palette.
+ * @returns The dialog select-list theme with a reverse-video selection.
+ */
+export function dialogSelectTheme(palette: Palette): SelectListTheme {
+  return {
+    ...selectTheme(palette),
+    selectedText: text => palette.selected(palette.accent(text)),
+  }
+}

packages/ui/tui/src/components/transcript.ts

@@ -0,0 +1,529 @@
+/**
+ * pi-tui transcript components: the startup banner, user/assistant messages,
+ * per-step timing footer, streaming assistant buffer, tool cards, and the todo
+ * panel. Each is a pure function of its inputs and the active palette.
+ * @module @deepseek-ai/dsh-tui/components/transcript
+ */
+
+import {
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  truncateToWidth,
+  wrapTextWithAnsi,
+  type Component,
+  type MarkdownTheme,
+} from '@earendil-works/pi-tui'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { JsonValue, SessionEvent, TodoItem } from '@deepseek-ai/dsh-session'
+import type {
+  TerminalCallView,
+  ToolCallView,
+  ToolDefinition,
+  ToolResultView,
+} from '@deepseek-ai/dsh-tools'
+import type { FileDiff } from '@deepseek-ai/dsh-tools'
+import { renderUnknownXml } from '../xml-tool-output.ts'
+import { displayInlineText, displayText } from './text.ts'
+import { gradientText, type Palette } from './theme.ts'
+import { contentText, type ParsedArguments } from './content.ts'
+import {
+  formatCompletionTime,
+  formatTimingTotals,
+  stepTimingAt,
+  type StepPosition,
+} from '../session/timing.ts'
+
+/** Concatenate the text of every block of one type, separated by blank lines. */
+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')
+}
+
+/** Render a value as terminal-safe text: strings escaped, other values as pretty JSON. */
+function pretty(value: unknown): string {
+  if (typeof value === 'string') return displayText(value)
+  // JSON.stringify is typed to return string but yields undefined for e.g. symbols.
+  const serialized = JSON.stringify(value, null, 2) as string | undefined
+  return displayText(serialized ?? String(value))
+}
+
+/** A file diff as colored `+`/`-` lines, optionally prefixed with its path. */
+function diffLines(diff: FileDiff, palette: Palette): string[] {
+  // The card header is a fixed `Tool / <name>` frame that never names a file, so
+  // each hunk always carries its own path header (no redundancy to suppress).
+  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
+}
+
+/**
+ * A message's bold, underlined role header in the role color. The underline
+ * bands each role without a background fill or per-line prefix, so it reads on
+ * any theme and a body drag-select copies the message text verbatim.
+ */
+function messageHeader(label: string, color: (text: string) => string, palette: Palette): string {
+  return palette.bold(palette.underline(color(displayText(label))))
+}
+
+/**
+ * Borderless startup banner: product title, an optional configured subtitle,
+ * and the session id. No box frame — each line renders as plain left-padded
+ * text (matching transcript notices) so it reads on any theme.
+ */
+export class HeaderComponent implements Component {
+  /** Columns of the banner currently revealed; `undefined` renders it whole. */
+  private revealWidth: number | undefined
+
+  constructor(
+    private readonly agent: Agent,
+    private readonly subtitle: () => string | undefined,
+    private readonly palette: Palette,
+    private readonly gradient: boolean,
+  ) {}
+
+  /**
+   * Clip the banner to `width` columns (the sweep reveal); `undefined` restores it.
+   * @param width - Revealed banner width in columns, or `undefined` for the whole banner.
+   */
+  setRevealWidth(width: number | undefined): void {
+    this.revealWidth = width
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const usable = Math.max(1, width - 2)
+    const name = this.gradient
+      ? this.palette.bold(gradientText('DEEPSEEK'))
+      : this.palette.bold(this.palette.accent('DEEPSEEK'))
+    const title = `${name} ${this.palette.bold('HARNESS')}`
+    const detail = displayText(this.agent.session.id)
+    const subtitle = this.subtitle()
+    const lines = [
+      title,
+      ...subtitle === undefined ? [] : [this.palette.muted(displayText(subtitle))],
+      this.palette.dim(detail),
+    ]
+      .flatMap(line => wrapTextWithAnsi(line, usable))
+      .map(line => ` ${truncateToWidth(line, usable, '')}`)
+    if (this.revealWidth === undefined) return lines
+    const revealed = this.revealWidth
+    return lines.map(line => truncateToWidth(line, revealed, ''))
+  }
+}
+
+/**
+ * A user or steering prompt in the transcript. An underlined accent role header
+ * plus blank-line spacing separate it from surrounding blocks; body lines carry
+ * no prefix or indent, so a terminal drag-select copies the prompt verbatim.
+ */
+export class UserMessageComponent extends Container {
+  constructor(text: string, palette: Palette, mdTheme: MarkdownTheme, label = 'You') {
+    super()
+    this.addChild(new Text(messageHeader(label, palette.accent, palette), 0, 0))
+    this.addChild(new Markdown(displayText(text), 0, 0, mdTheme, { color: value => palette.text(value) }, {
+      preserveOrderedListMarkers: true,
+      preserveBackslashEscapes: true,
+    }))
+  }
+}
+
+/** Children of a settled assistant message: optional reasoning block then the response text. */
+function assistantMessageChildren(
+  content: readonly ContentBlock[],
+  showReasoning: boolean,
+  palette: Palette,
+  mdTheme: MarkdownTheme,
+): Component[] {
+  const reasoning = displayText(textBlocks(content, 'reasoning').trim())
+  const text = displayText(textBlocks(content, 'text').trim())
+  const children: Component[] = [
+    new Spacer(1),
+    new Text(messageHeader('Assistant', palette.accent2, palette), 0, 0),
+  ]
+  if (reasoning && showReasoning) {
+    children.push(
+      new Text(palette.italic(palette.muted('Reasoning')), 0, 0),
+      new Markdown(reasoning, 0, 0, mdTheme, { color: value => palette.muted(value), italic: true }),
+    )
+  }
+  if (text) children.push(new Markdown(text, 0, 0, mdTheme, { color: value => palette.text(value) }))
+  return children
+}
+
+/**
+ * A step's timing summary, rendered as a self-refreshing footer that stays at
+ * the tail of the step's output. Kept separate from the assistant message so
+ * the timing line trails any tool cards the step appends after its message.
+ */
+class StepTimingComponent extends Container {
+  private completionTime: number | undefined
+
+  constructor(
+    private readonly position: StepPosition,
+    private readonly events: () => readonly SessionEvent[],
+    private readonly now: () => number,
+    private readonly palette: Palette,
+  ) {
+    super()
+    this.rebuild()
+  }
+
+  complete(time: number): void {
+    this.completionTime = time
+    this.rebuild()
+  }
+
+  override invalidate(): void {
+    this.rebuild()
+    super.invalidate()
+  }
+
+  private rebuild(): void {
+    this.clear()
+    const totals = stepTimingAt(this.events(), this.position, this.completionTime ?? this.now())
+    const timing = formatTimingTotals(totals, true)
+    const header = this.completionTime === undefined
+      ? timing
+      : `${timing} · Completed ${formatCompletionTime(this.completionTime)}`
+    this.addChild(new Text(this.palette.dim(header), 0, 0))
+  }
+}
+
+interface StreamingBlock {
+  type: string
+  text: string
+}
+
+/** A live assistant step: streamed reasoning/text blocks until the message settles. */
+export class StreamingAssistantComponent extends Container {
+  private readonly blocks = new Map<number, StreamingBlock>()
+  private settledContent: readonly ContentBlock[] | undefined
+  /**
+   * The step's timing footer. The renderer keeps it at the tail of the chat so
+   * it trails any tool cards the step appends after this assistant message; it
+   * is not a child of this component.
+   */
+  readonly timing: StepTimingComponent
+
+  constructor(
+    position: StepPosition,
+    events: () => readonly SessionEvent[],
+    now: () => number,
+    private showReasoning: boolean,
+    private readonly palette: Palette,
+    private readonly mdTheme: MarkdownTheme,
+  ) {
+    super()
+    this.timing = new StepTimingComponent(position, events, now, palette)
+    this.rebuild()
+  }
+
+  /**
+   * Replace the streamed blocks with the step's settled content.
+   * @param content - The settled assistant content blocks.
+   */
+  settle(content: readonly ContentBlock[]): void {
+    this.settledContent = content
+    this.rebuild()
+  }
+
+  /**
+   * Whether this step's assistant message has settled.
+   * @returns `true` once {@link settle} has run.
+   */
+  isSettled(): boolean {
+    return this.settledContent !== undefined
+  }
+
+  /**
+   * Pin the step's timing footer to its completion time.
+   * @param time - Step completion time in epoch milliseconds.
+   */
+  complete(time: number): void {
+    this.timing.complete(time)
+  }
+
+  override invalidate(): void {
+    this.rebuild()
+    this.timing.invalidate()
+    super.invalidate()
+  }
+
+  /**
+   * Fold one streamed chunk into the live block buffer and re-render.
+   * @param chunk - The streamed assistant chunk.
+   */
+  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()
+    this.timing.invalidate()
+  }
+
+  /**
+   * Toggle whether reasoning blocks render, then re-render.
+   * @param show - Whether to show reasoning blocks.
+   */
+  setShowReasoning(show: boolean): void {
+    this.showReasoning = show
+    this.rebuild()
+  }
+
+  private rebuild(): void {
+    this.clear()
+    const content: readonly ContentBlock[] = this.settledContent ?? [...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 []
+      })
+    for (const child of assistantMessageChildren(content, this.showReasoning, this.palette, this.mdTheme)) {
+      this.addChild(child)
+    }
+  }
+}
+
+/** A tool call and its result, rendered as a collapsible status card. */
+export class ToolCardComponent implements Component {
+  private result: { content: ContentBlock[]; isError: boolean; meta?: JsonValue } | 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,
+    private readonly mdTheme: MarkdownTheme,
+  ) {
+    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 }
+  }
+
+  /**
+   * Record the tool result and derive its result view.
+   * @param event - The `tool/result` event payload.
+   */
+  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)}` }] }
+      }
+    }
+  }
+
+  /**
+   * Expand or collapse the card's body preview.
+   * @param expanded - Whether the full body is shown.
+   */
+  setExpanded(expanded: boolean): void {
+    this.expanded = expanded
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const isError = this.result?.isError ?? false
+    // A ring marker: hollow while the call is pending, filled once it settles;
+    // the header color (warning/success/error) tells pending from ok from error.
+    const glyph = this.result === undefined ? '○' : '●'
+    const rawBody = this.renderBody()
+    const view = this.resultView ?? this.callView
+    const genericContent = view.card === 'generic' ? view.content ?? this.result?.content : undefined
+    const unknownXml = this.definition === undefined && genericContent !== undefined
+      ? renderUnknownXml(
+        displayText(contentText(genericContent)),
+        this.maxOutputLines,
+        this.expanded,
+        displayText,
+        text => this.palette.muted(text),
+        /* v8 ignore next -- renderUnknownXml calls the collapsed summary only when hidden XML children exceed this card's limit. */
+        count => this.palette.dim(`  … +${count} lines (Ctrl+O to expand)`),
+      )
+      : undefined
+    const body = unknownXml ?? (genericContent !== undefined && rawBody.length > 0
+      ? new Markdown(rawBody.join('\n'), 0, 0, this.mdTheme, { color: value => this.palette.text(value) }).render(width)
+      : rawBody)
+    const headLines = Math.ceil(this.maxOutputLines / 2)
+    const tailLines = this.maxOutputLines - headLines
+    const visibleBody = unknownXml !== undefined || this.expanded || body.length <= this.maxOutputLines
+      ? body
+      : [
+        ...body.slice(0, headLines),
+        this.palette.dim(`… +${body.length - this.maxOutputLines} lines (Ctrl+O to expand)`),
+        ...body.slice(body.length - tailLines),
+      ]
+    // The header is a fixed `Tool / <name>` frame in the status color (warning
+    // pending / success ok / error), flat — no bold or underline, so one color
+    // reads consistently across the whole row. Every tool-specific detail (a
+    // read's path, a diff, command output) lives in the body below; the sole
+    // header extra is a bash card's model-authored description, appended as a
+    // `/ <desc>` segment. The body stays unprefixed so a drag-select copies only
+    // the tool text; body lines pass through Text so overlong output wraps.
+    const statusColor = this.result === undefined
+      ? this.palette.warning
+      : isError ? this.palette.error : this.palette.success
+    // The header is a single card row: collapse an embedded newline in the
+    // description to an inline escape so it cannot break onto extra rows and
+    // collide with the body lines that follow.
+    const desc = this.headerDescription()
+    const headerText = `${glyph} Tool / ${displayText(this.name)}${desc === undefined ? '' : ` / ${displayInlineText(desc)}`}`
+    const header = truncateToWidth(headerText, Math.max(1, width - 2), '')
+    const lines = [statusColor(header)]
+    if (visibleBody.length > 0) lines.push(...new Text(visibleBody.join('\n'), 0, 0).render(width))
+    return lines
+  }
+
+  /** The pending terminal call view, when this row is a terminal card. */
+  private terminalPending(): TerminalCallView | undefined {
+    return this.callView.card === 'terminal' ? this.callView : undefined
+  }
+
+  /**
+   * The optional header `/ <desc>` segment: a bash (terminal) card's
+   * model-authored description. Non-terminal tools contribute no header detail —
+   * their presenter title moves into the body instead.
+   */
+  private headerDescription(): string | undefined {
+    const description = this.terminalPending()?.description
+    return description !== undefined && description !== '' ? description : undefined
+  }
+
+  /**
+   * The presenter's title for a non-terminal card, shown as the first body line
+   * (a read's `Read src/foo.ts`, a diff's `Edit files`) now that the header is a
+   * fixed `Tool / <name>` frame. The result-state title replaces the pending one.
+   */
+  private bodyTitle(): string {
+    return this.resultView?.title ?? this.callView.title
+  }
+
+  private renderBody(): string[] {
+    const view = this.resultView ?? this.callView
+    if (view.card === 'terminal') {
+      const pending = this.terminalPending()
+      const lines: string[] = []
+      // The command shows as a $-line here whenever it is not the header: either a
+      // description headlines the row (the command still belongs somewhere) or the row
+      // is a pending undescribed call (the classic running-command echo). A completed
+      // undescribed row keeps the command only in the header.
+      // The command and cwd are each a single card row, so escape a multi-line
+      // command inline (displayInlineText) — a real newline would break onto extra
+      // rows and collide with the output below.
+      const headlined = pending?.description !== undefined && pending.description !== ''
+      const commandInBody = pending !== undefined && (headlined || this.result === undefined)
+      if (commandInBody) lines.push(this.palette.code(`$ ${displayInlineText(pending.title)}`))
+      if (pending?.cwd) lines.push(this.palette.dim(displayInlineText(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) {
+        lines.push(...displayText(contentText(this.result.content)).split('\n'))
+      }
+      return lines.filter(Boolean)
+    }
+    if (view.card === 'diff') {
+      // The header no longer names the file, so each diff keeps its own path
+      // header. A trailing footer summarizes the change (`+A -R · N file(s)`).
+      let added = 0
+      let removed = 0
+      const hunks = view.diffs.flatMap((diff, index) => {
+        if (diff.oldText !== null) removed += displayText(diff.oldText).split('\n').length
+        added += displayText(diff.newText).split('\n').length
+        return [...index > 0 ? [''] : [], ...diffLines(diff, this.palette)]
+      })
+      const files = view.diffs.length
+      const footer = this.palette.dim(`└ +${added} -${removed} · ${files} file${files === 1 ? '' : 's'}`)
+      return [...hunks, footer]
+    }
+    const content = view.content ?? this.result?.content
+    const lines: string[] = []
+    // The presenter title headlines the body now that the header is a fixed
+    // `Tool / <name>` frame (a terminal card keeps its command $-line instead).
+    // Skip it when it only repeats the tool name (the fallback presenter for a
+    // tool with no presentCall, or an unknown tool), which the header already shows.
+    const bodyTitle = this.bodyTitle()
+    if (bodyTitle !== displayText(this.name)) lines.push(displayInlineText(bodyTitle))
+    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))
+  }
+}
+
+/** The plan/todo panel rendered above the prompt. */
+export class TodoComponent implements Component {
+  private todos: readonly TodoItem[] = []
+
+  constructor(private readonly palette: Palette) {}
+
+  /**
+   * Replace the rendered plan items.
+   * @param todos - The current todo items.
+   */
+  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]
+  }
+}

packages/ui/tui/src/config.ts

@@ -0,0 +1,213 @@
+/**
+ * Serializable configuration and defaults for the pi-tui terminal mode. Loader
+ * schema validation normally fills defaults; {@link resolveTuiConfig} applies
+ * the same defaults for direct callers that bypass the Loader.
+ * @module @deepseek-ai/dsh-tui/config
+ */
+
+import z from 'schemastery'
+import {
+  DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES,
+  DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+  DEFAULT_FILE_SEARCH_MAX_RESULTS,
+} from './file-autocomplete.ts'
+
+/** Theme and prompt-template settings for the pi-tui terminal mode. */
+export interface TuiThemeConfig {
+  /** Apply the built-in ANSI color palette. */
+  color?: boolean
+  /** Paint the startup banner with the 24-bit DeepSeek brand gradient. */
+  truecolor?: boolean
+  /** Left-aligned template on the row above the editor. */
+  leftPrompt?: string
+  /** Right-aligned template on the row above the editor. */
+  rightPrompt?: string
+  /** Template used as the editor's first-line prefix. */
+  inputPrompt?: string
+  /** Static placeholder shown in an empty editor while the agent is running. */
+  inputPlaceholder?: string
+}
+
+/** Interaction and presentation settings for the pi-tui terminal mode. */
+export interface TuiConfig {
+  /** Render model reasoning blocks. */
+  showReasoning?: boolean
+  /** Maximum tool-card body lines retained in its collapsed head/tail preview. */
+  maxToolOutputLines?: number
+  /** Maximum options visible at once in a user-question panel. */
+  maxQuestionOptions?: number
+  /** Maximum models visible at once in the model selector. */
+  maxModelOptions?: number
+  /** Maximum sessions visible at once in the resume selector. */
+  maxResumeOptions?: number
+  /** User-question panel width in terminal columns, clamped to the terminal. */
+  questionDialogWidth?: number
+  /** User-question panel maximum height in terminal rows. */
+  questionDialogMaxHeight?: number
+  /** Model-selector width in terminal columns. */
+  modelDialogWidth?: number
+  /** Model-selector maximum height in terminal rows. */
+  modelDialogMaxHeight?: number
+  /** Maximum fuzzy file candidates displayed for one `@` query. */
+  fileSearchMaxResults?: number
+  /** Maximum paths retained in one `@` workspace index. */
+  fileSearchMaxEntries?: number
+  /** Directory basenames excluded from `@` traversal and completion. */
+  fileSearchExcludedDirectories?: string[]
+  /** Show the terminal's hardware cursor at the pi editor's IME marker. */
+  showHardwareCursor?: boolean
+  /** Color and prompt-template settings. */
+  theme?: TuiThemeConfig
+  /** Terminal window title while the UI is mounted; a logged session title prefixes it. */
+  title?: string
+}
+
+const showReasoningSchema = z.boolean().default(true)
+const maxToolOutputLinesSchema = z.number().step(1).min(1).default(6)
+const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
+const maxModelOptionsSchema = z.number().step(1).min(1).default(8)
+const maxResumeOptionsSchema = z.number().step(1).min(1).default(8)
+const questionDialogWidthSchema = z.number().step(1).min(20).default(200)
+const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
+const modelDialogWidthSchema = z.number().step(1).min(20).default(76)
+const modelDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
+const fileSearchMaxResultsSchema = z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_RESULTS)
+const fileSearchMaxEntriesSchema = z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_ENTRIES)
+const fileSearchExcludedDirectoriesSchema = z.array(z.string()).default([...DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES])
+const showHardwareCursorSchema = z.boolean().default(false)
+const colorSchema = z.boolean().default(true)
+// No default: an unset value auto-detects truecolor from COLORTERM in `apply`.
+const truecolorSchema = z.boolean()
+const DEFAULT_LEFT_PROMPT = '${cwd}${git/worktree}${model}${token_meter/cache_hit_rate}${context}'
+const DEFAULT_RIGHT_PROMPT = '${timing}'
+const DEFAULT_INPUT_PROMPT = '${symbol} ${indicator}'
+const DEFAULT_INPUT_PLACEHOLDER = 'press enter to steer and esc to cancel'
+const TuiThemeConfigSchema: z<TuiThemeConfig> = z.object({
+  color: colorSchema,
+  truecolor: truecolorSchema,
+  leftPrompt: z.string().default(DEFAULT_LEFT_PROMPT),
+  rightPrompt: z.string().default(DEFAULT_RIGHT_PROMPT),
+  inputPrompt: z.string().default(DEFAULT_INPUT_PROMPT),
+  inputPlaceholder: z.string().default(DEFAULT_INPUT_PLACEHOLDER),
+})
+const titleSchema = z.string().default('DeepSeek Harness')
+
+const tuiConfigSchemaFields = {
+  showReasoning: showReasoningSchema,
+  maxToolOutputLines: maxToolOutputLinesSchema,
+  maxQuestionOptions: maxQuestionOptionsSchema,
+  maxModelOptions: maxModelOptionsSchema,
+  maxResumeOptions: maxResumeOptionsSchema,
+  questionDialogWidth: questionDialogWidthSchema,
+  questionDialogMaxHeight: questionDialogMaxHeightSchema,
+  modelDialogWidth: modelDialogWidthSchema,
+  modelDialogMaxHeight: modelDialogMaxHeightSchema,
+  fileSearchMaxResults: fileSearchMaxResultsSchema,
+  fileSearchMaxEntries: fileSearchMaxEntriesSchema,
+  fileSearchExcludedDirectories: fileSearchExcludedDirectoriesSchema,
+  showHardwareCursor: showHardwareCursorSchema,
+  theme: TuiThemeConfigSchema,
+  title: titleSchema,
+}
+
+/** Schemastery schema for presentation settings embedded by app bundles. */
+export const TuiConfigSchema: z<TuiConfig> = z.object(tuiConfigSchemaFields)
+
+/** Serializable plugin configuration. */
+export interface Config extends TuiConfig {
+  /** Banner subtitle line. When absent, the banner has no subtitle and sweeps in on start. */
+  welcome?: string
+  /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
+  sessionId?: string
+  /**
+   * Shell command fallback printed on exit or after selecting a session when
+   * the host cannot hand off in place. Every `{session}` becomes the selected
+   * id; the TUI never executes this text. Absent disables only the fallback,
+   * not the interactive selector.
+   */
+  resumeCommand?: string
+}
+
+/** Schemastery schema for the full plugin configuration. */
+export const Config: z<Config> = z.object({
+  welcome: z.string(),
+  sessionId: z.string().default('main'),
+  resumeCommand: z.string(),
+  showReasoning: tuiConfigSchemaFields.showReasoning,
+  maxToolOutputLines: tuiConfigSchemaFields.maxToolOutputLines,
+  maxQuestionOptions: tuiConfigSchemaFields.maxQuestionOptions,
+  maxModelOptions: tuiConfigSchemaFields.maxModelOptions,
+  maxResumeOptions: tuiConfigSchemaFields.maxResumeOptions,
+  questionDialogWidth: tuiConfigSchemaFields.questionDialogWidth,
+  questionDialogMaxHeight: tuiConfigSchemaFields.questionDialogMaxHeight,
+  modelDialogWidth: tuiConfigSchemaFields.modelDialogWidth,
+  modelDialogMaxHeight: tuiConfigSchemaFields.modelDialogMaxHeight,
+  fileSearchMaxResults: tuiConfigSchemaFields.fileSearchMaxResults,
+  fileSearchMaxEntries: tuiConfigSchemaFields.fileSearchMaxEntries,
+  fileSearchExcludedDirectories: tuiConfigSchemaFields.fileSearchExcludedDirectories,
+  showHardwareCursor: tuiConfigSchemaFields.showHardwareCursor,
+  theme: tuiConfigSchemaFields.theme,
+  title: tuiConfigSchemaFields.title,
+})
+
+/** Fully defaulted TUI theme settings. */
+export interface ResolvedTuiThemeConfig {
+  color: boolean
+  truecolor: boolean
+  leftPrompt: string
+  rightPrompt: string
+  inputPrompt: string
+  inputPlaceholder: string
+}
+
+/** Fully defaulted TUI presentation settings. */
+export interface ResolvedTuiConfig {
+  showReasoning: boolean
+  maxToolOutputLines: number
+  maxQuestionOptions: number
+  maxModelOptions: number
+  maxResumeOptions: number
+  questionDialogWidth: number
+  questionDialogMaxHeight: number
+  modelDialogWidth: number
+  modelDialogMaxHeight: number
+  fileSearchMaxResults: number
+  fileSearchMaxEntries: number
+  fileSearchExcludedDirectories: string[]
+  showHardwareCursor: boolean
+  theme: ResolvedTuiThemeConfig
+  title: string
+}
+
+/**
+ * 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 ?? 6,
+    maxQuestionOptions: config?.maxQuestionOptions ?? 8,
+    maxModelOptions: config?.maxModelOptions ?? 8,
+    maxResumeOptions: config?.maxResumeOptions ?? 8,
+    questionDialogWidth: config?.questionDialogWidth ?? 200,
+    questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
+    modelDialogWidth: config?.modelDialogWidth ?? 76,
+    modelDialogMaxHeight: config?.modelDialogMaxHeight ?? 20,
+    fileSearchMaxResults: config?.fileSearchMaxResults ?? DEFAULT_FILE_SEARCH_MAX_RESULTS,
+    fileSearchMaxEntries: config?.fileSearchMaxEntries ?? DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+    fileSearchExcludedDirectories: [...(config?.fileSearchExcludedDirectories ?? DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES)],
+    showHardwareCursor: config?.showHardwareCursor ?? false,
+    theme: {
+      color: config?.theme?.color ?? true,
+      truecolor: config?.theme?.truecolor ?? false,
+      leftPrompt: config?.theme?.leftPrompt ?? DEFAULT_LEFT_PROMPT,
+      rightPrompt: config?.theme?.rightPrompt ?? DEFAULT_RIGHT_PROMPT,
+      inputPrompt: config?.theme?.inputPrompt ?? DEFAULT_INPUT_PROMPT,
+      inputPlaceholder: config?.theme?.inputPlaceholder ?? DEFAULT_INPUT_PLACEHOLDER,
+    },
+    title: config?.title ?? 'DeepSeek Harness',
+  }
+}

packages/ui/tui/src/overlay-manager.ts → packages/ui/tui/src/extension/overlay-manager.ts

@@ -3,12 +3,12 @@
  *
  * The manager serializes modal ownership, guards extension callbacks, and
  * settles every queued or active operation before terminal teardown.
- * @module @deepseek-ai/dsh-tui/overlay-manager
+ * @module @deepseek-ai/dsh-tui/extension/overlay-manager
  */
 
 import { Service, type Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { TuiExtensionService } from './index.ts'
+import type { TuiExtensionService } from '../index.ts'
 import type {
   Component,
   Focusable,
@@ -26,7 +26,7 @@ import type {
   TuiOverlayState,
   TuiTheme,
   TuiViewport,
-} from './extension.ts'
+} from './types.ts'
 
 /** pi-tui operations retained by the front door instead of exposed to plugins. */
 export interface TuiOverlayDriver {

packages/ui/tui/src/extension.ts → packages/ui/tui/src/extension/types.ts

@@ -5,7 +5,7 @@
  * the live pi-tui tree, focus controller, overlay handles, or terminal
  * lifecycle. Registrations and open overlays remain owned by the calling
  * Cordis fiber.
- * @module @deepseek-ai/dsh-tui/extension
+ * @module @deepseek-ai/dsh-tui/extension/types
  */
 
 /** Terminal component shape accepted from a trusted TUI extension. */

packages/ui/tui/src/prompt.ts

@@ -0,0 +1,217 @@
+/**
+ * Mutable terminal-prompt value registry consumed by the TUI template renderer.
+ * Values are trusted presentation fragments and may contain ANSI control sequences.
+ * @module @deepseek-ai/dsh-tui/prompt
+ */
+
+import { Context, Service } from 'cordis'
+import { errorChain } from '@deepseek-ai/dsh-llm'
+
+export const name = 'tui-prompt'
+
+const VALUE_NAME = /^[a-z][a-z0-9_-]*(?:\/[a-z][a-z0-9_-]*)*$/u
+
+/** Handle owned by one prompt-value registration. */
+export interface TuiPromptValueHandle {
+  /**
+   * Replace the current fragment and schedule a coalesced change notification
+   * so the owning renderer redraws. Setting the current value again is a no-op.
+   * @param value - Trusted ANSI-capable fragment, or `undefined` while unavailable.
+   */
+  set(value: string | undefined): void
+
+  /** Unregister this value; subsequent {@link TuiPromptValueHandle.set} calls fail. */
+  dispose(): void
+}
+
+interface RegisteredValue {
+  value: string | undefined
+}
+
+declare module 'cordis' {
+  interface Context {
+    tuiPrompt: TuiPromptService
+  }
+}
+
+/** Removes a change subscription registered with {@link TuiPromptService.subscribe}. */
+export type TuiPromptUnsubscribe = () => void
+
+/** One literal or variable token in a parsed TUI prompt template. */
+export type TuiPromptTemplateToken =
+  | { readonly kind: 'literal'; readonly value: string }
+  | { readonly kind: 'value'; readonly name: string }
+
+/**
+ * Parse a prompt template into immutable literal and value tokens.
+ * @param template - Text containing `${name}` references.
+ * @returns Tokens consumed by {@link renderTuiPromptTemplate}.
+ */
+export function parseTuiPromptTemplate(template: string): readonly TuiPromptTemplateToken[] {
+  const tokens: TuiPromptTemplateToken[] = []
+  const pattern = /\$\{([^}]*)\}/gu
+  let offset = 0
+  for (const match of template.matchAll(pattern)) {
+    const index = match.index
+    const name = match[1]
+    /* v8 ignore next -- the sole capture always exists when this pattern matches. */
+    if (name === undefined) continue
+    if (index > offset) tokens.push(Object.freeze({ kind: 'literal', value: template.slice(offset, index) }))
+    tokens.push(Object.freeze({ kind: 'value', name }))
+    offset = index + match[0].length
+  }
+  if (offset < template.length) tokens.push(Object.freeze({ kind: 'literal', value: template.slice(offset) }))
+  return Object.freeze(tokens)
+}
+
+/**
+ * Interpolate one parsed prompt while removing horizontal separators adjacent
+ * only to unavailable values.
+ * @param tokens - Parsed template tokens.
+ * @param resolve - Current value lookup.
+ * @returns ANSI-capable rendered prompt text.
+ */
+export function renderTuiPromptTemplate(
+  tokens: readonly TuiPromptTemplateToken[],
+  resolve: (name: string) => string | undefined,
+): string {
+  const rendered: string[] = []
+  let omitLeadingWhitespace = false
+  for (const token of tokens) {
+    if (token.kind === 'value') {
+      const value = resolve(token.name)
+      if (value === undefined) {
+        omitLeadingWhitespace = true
+      } else {
+        rendered.push(value)
+        omitLeadingWhitespace = false
+      }
+      continue
+    }
+    rendered.push(omitLeadingWhitespace ? token.value.replace(/^[\t ]+/u, '') : token.value)
+    omitLeadingWhitespace = false
+  }
+  return rendered.join('')
+}
+
+/**
+ * Context-global mutable values interpolated by TUI theme prompt templates.
+ * A registration, mutation, or disposal schedules one coalesced notification to
+ * the renderer subscribed with {@link TuiPromptService.subscribe}, so a value
+ * that changes on its own schedule (not only in response to a UI event) still
+ * redraws. Notification is a direct in-service callback, not a Cordis event.
+ */
+export class TuiPromptService extends Service {
+  private readonly values = new Map<string, RegisteredValue>()
+  // Per-subscription record identity, not callback identity: two fibers may
+  // subscribe the same function, and disposing one must not remove the other's.
+  private readonly listeners = new Set<{ readonly listener: () => unknown }>()
+  private notificationQueued = false
+
+  constructor(ctx: Context) {
+    super(ctx, 'tuiPrompt')
+  }
+
+  /**
+   * Register one globally unique template value under the calling Cordis effect.
+   * @param name - Lowercase slash-separated template name.
+   * @param initialValue - Initial trusted ANSI-capable fragment.
+   * @returns A mutable handle whose disposal unregisters the name.
+   */
+  register(name: string, initialValue?: string): TuiPromptValueHandle {
+    if (!VALUE_NAME.test(name)) {
+      throw new TypeError(`TUI prompt value name "${name}" must match ${String(VALUE_NAME)}`)
+    }
+    if (this.values.has(name)) throw new Error(`TUI prompt value "${name}" is already registered`)
+
+    const registered: RegisteredValue = { value: initialValue }
+    let active = true
+    const effectDisposer = this.ctx.effect(() => {
+      this.values.set(name, registered)
+      this.scheduleChange()
+      // Cordis runs this cleanup at most once per effect, and deleting an
+      // absent key is a no-op, so no re-entrancy guard is needed here; `active`
+      // exists only to reject a late {@link TuiPromptValueHandle.set}.
+      return () => {
+        active = false
+        this.values.delete(name)
+        this.scheduleChange()
+      }
+    }, `tuiPrompt.register(${name})`)
+
+    return Object.freeze({
+      set: (value: string | undefined): void => {
+        if (!active) throw new Error(`TUI prompt value "${name}" is disposed`)
+        if (registered.value === value) return
+        registered.value = value
+        this.scheduleChange()
+      },
+      dispose: (): void => { void effectDisposer() },
+    })
+  }
+
+  /**
+   * Read a registered fragment without evaluating plugin code.
+   * @param name - Exact registered template name.
+   * @returns The current fragment, or `undefined` when unknown or unavailable.
+   */
+  get(name: string): string | undefined {
+    return this.values.get(name)?.value
+  }
+
+  /**
+   * Observe registration and value changes. The listener runs after a coalesced
+   * microtask following any burst of mutations; the renderer re-reads current
+   * values on that callback. The subscription is owned by the calling Cordis
+   * effect, so it is removed when the subscriber's fiber disposes; the returned
+   * disposer removes it early. Listener failures are contained — a synchronous
+   * throw or a rejected returned promise cannot starve the other observers.
+   * @param listener - Invoked once per coalesced change burst. Delivery does
+   *   not wait on a returned promise; its rejection is only observed and logged,
+   *   never left unhandled, so an async listener cannot order later observers.
+   * @returns A disposer that removes the subscription.
+   */
+  subscribe(listener: () => unknown): TuiPromptUnsubscribe {
+    const record = { listener }
+    const disposeEffect = this.ctx.effect(() => {
+      this.listeners.add(record)
+      return () => { this.listeners.delete(record) }
+    }, 'tuiPrompt.subscribe')
+    return () => { void disposeEffect() }
+  }
+
+  /** Coalesce mutation bursts into one notification while containing each observer. */
+  private scheduleChange(): void {
+    if (this.notificationQueued) return
+    this.notificationQueued = true
+    queueMicrotask(() => {
+      this.notificationQueued = false
+      // Snapshot so a listener may subscribe/unsubscribe during delivery, but
+      // re-check liveness: a listener that synchronously unsubscribes another
+      // observer earlier in the same burst must silence it now, keeping the
+      // subscription set authoritative during reentrant notification.
+      for (const record of [...this.listeners]) {
+        if (this.listeners.has(record)) this.notifyOne(record.listener)
+      }
+    })
+  }
+
+  /** Deliver one change notification, containing a synchronous throw or a rejected promise. */
+  private notifyOne(listener: () => unknown): void {
+    let returned: unknown
+    try {
+      returned = listener()
+    } catch (error: unknown) {
+      // errorChain never throws, even on a hostile toString/getter, so the
+      // notification microtask can never escape to starve later observers.
+      this.ctx.logger.warn(`tui-prompt change listener threw: ${errorChain(error)}`)
+      return
+    }
+    // A listener may be async; contain a rejected promise the same as a throw.
+    void Promise.resolve(returned).catch((error: unknown) => {
+      this.ctx.logger.warn(`tui-prompt change listener rejected: ${errorChain(error)}`)
+    })
+  }
+}
+
+export default TuiPromptService

packages/ui/tui/src/session/timing.ts

@@ -0,0 +1,357 @@
+/**
+ * Per-step timing model and running-status glyph animation for the terminal
+ * front door. Timing buckets are replayed from the session event stream; the
+ * running glyph fades in on turn start, throbs while the turn runs, and fades
+ * out on turn end.
+ * @module @deepseek-ai/dsh-tui/session/timing
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Palette } from '../components/theme.ts'
+
+/**
+ * Render cadence of the running prompt while active, and while the glyph fades
+ * out after a turn ends. ~20 fps so the truecolor glyph fade reads smoothly;
+ * the same tick keeps the elapsed-time text (0.1 s resolution) current. Only
+ * changed terminal cells are re-emitted, so the faster tick stays cheap.
+ */
+export const STATUS_ANIMATION_INTERVAL_MS = 50
+
+/**
+ * Milliseconds over which the running glyph fades in when a turn starts and
+ * fades out after it ends. The fade is an envelope over the running pulse:
+ * inside it the glyph throbs (see {@link STATUS_PULSE_PERIOD_MS}).
+ */
+export const STATUS_FADE_MS = 300
+
+/** Milliseconds for one full brightness throb of the running glyph. */
+export const STATUS_PULSE_PERIOD_MS = 1400
+
+/**
+ * Brightness floor of the running throb, as a fraction of the settled gray. At
+ * 0 the pulse swells from fully invisible (a blank glyph column, see
+ * {@link STATUS_FADE_MIN_OPACITY}) up to full and back, so the dimmest point of
+ * each breath truly disappears rather than lingering as a faint mark.
+ */
+export const STATUS_PULSE_FLOOR = 0
+
+/**
+ * Opacity below which the truecolor running glyph is hidden entirely (a blank
+ * column) instead of painted as a near-background gray, so the trough of the
+ * pulse reads as invisible. The fixed glyph width is preserved by the blank.
+ */
+export const STATUS_FADE_MIN_OPACITY = 0.12
+
+/**
+ * Muted-gray foreground the truecolor running glyph fades through, from the
+ * near-background trough (opacity 0) to the settled dim gray (opacity 1). Same
+ * hue-free gray as the idle caret, so the glyph reads as the caret dimly
+ * appearing rather than a colored indicator. Foreground-only, matching the
+ * brand gradient, so it stays legible on any terminal background.
+ */
+const STATUS_FADE_GRAY = {
+  trough: [43, 43, 43],
+  settled: [136, 136, 136],
+} as const
+
+/** The active phase of a running step, one bucket of accumulated wall time. */
+export type TimingBucket = 'ttft' | 'thinking' | 'responding' | 'tools'
+
+/** Turn/step coordinates of one assistant step. */
+export type StepPosition = { turn: number; step: number }
+
+/** Accumulated wall time per phase for one step or session slice. */
+export interface TimingTotals {
+  ttft: number
+  thinking: number
+  responding: number
+  tools: number
+}
+
+interface TimingState {
+  totals: TimingTotals
+  active: { bucket: TimingBucket; since: number } | undefined
+}
+
+const TIMING_BUCKET_LABELS: Record<TimingBucket, string> = {
+  ttft: 'Model wait',
+  thinking: 'Thinking',
+  responding: 'Response',
+  tools: 'Tools',
+}
+
+const TIMING_BUCKETS: readonly TimingBucket[] = ['ttft', 'thinking', 'responding', 'tools']
+
+function emptyTimingTotals(): TimingTotals {
+  return { ttft: 0, thinking: 0, responding: 0, tools: 0 }
+}
+
+function timingState(startedAt?: number): TimingState {
+  return {
+    totals: emptyTimingTotals(),
+    /* v8 ignore next -- production timing state always begins at a logged step timestamp. */
+    active: startedAt === undefined ? undefined : { bucket: 'ttft', since: startedAt },
+  }
+}
+
+function sameStep(event: SessionEvent, position: StepPosition): boolean {
+  return typeof event.data === 'object'
+    && 'turn' in event.data && 'step' in event.data
+    && event.data.turn === position.turn && event.data.step === position.step
+}
+
+function closeTimingBucket(state: TimingState, at: number): void {
+  if (state.active === undefined) return
+  state.totals[state.active.bucket] += Math.max(0, at - state.active.since)
+  state.active = undefined
+}
+
+function enterTimingBucket(state: TimingState, bucket: TimingBucket | undefined, at: number): void {
+  if (state.active?.bucket === bucket) return
+  closeTimingBucket(state, at)
+  if (bucket !== undefined) state.active = { bucket, since: at }
+}
+
+function advanceStepTiming(
+  state: TimingState,
+  event: Extract<SessionEvent, { type: 'assistant/chunk' | 'tool/call' | 'step/end' }>,
+): void {
+  if (event.type === 'assistant/chunk') {
+    const chunk = event.data.chunk
+    if (state.active?.bucket === 'ttft') enterTimingBucket(state, undefined, event.time)
+    if (chunk.type === 'reasoning-delta' || (chunk.type === 'block-start' && chunk.blockType === 'reasoning')) {
+      enterTimingBucket(state, 'thinking', event.time)
+    } else if (chunk.type === 'text-delta' || (chunk.type === 'block-start' && chunk.blockType === 'text')) {
+      enterTimingBucket(state, 'responding', event.time)
+    }
+  } else if (event.type === 'tool/call') {
+    enterTimingBucket(state, 'tools', event.time)
+  } else {
+    closeTimingBucket(state, event.time)
+  }
+}
+
+function timingTotalsAt(state: TimingState, at?: number): TimingTotals {
+  const totals = { ...state.totals }
+  if (state.active !== undefined && at !== undefined) {
+    totals[state.active.bucket] += Math.max(0, at - state.active.since)
+  }
+  return totals
+}
+
+/**
+ * Replay one step's accumulated per-phase timing up to clock `at`.
+ * @param events - Session events to replay.
+ * @param position - Turn/step coordinates of the step.
+ * @param at - Render clock to accumulate the open bucket up to.
+ * @returns The step's per-phase totals.
+ */
+export function stepTimingAt(
+  events: readonly SessionEvent[],
+  position: StepPosition,
+  at: number,
+): TimingTotals {
+  const startIndex = events.findIndex(event => event.type === 'step/start' && sameStep(event, position))
+  if (startIndex < 0) return emptyTimingTotals()
+  const start = events[startIndex] as Extract<SessionEvent, { type: 'step/start' }>
+  const state = timingState(start.time)
+  for (let index = startIndex + 1; index < events.length; index += 1) {
+    const event = events[index] as SessionEvent
+    if (event.time > at) break
+    if ((event.type === 'assistant/chunk' || event.type === 'tool/call' || event.type === 'step/end')
+      && sameStep(event, position)) {
+      advanceStepTiming(state, event)
+      if (event.type === 'step/end') break
+    }
+  }
+  return timingTotalsAt(state, at)
+}
+
+/**
+ * The turn index of the currently open turn, or `undefined` when none is open.
+ * @param events - Session events to scan from the tail.
+ * @returns The open turn index, or `undefined`.
+ */
+export function openTurn(events: readonly SessionEvent[]): number | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index] as SessionEvent
+    if (event.type === 'turn/end') return undefined
+    if (event.type === 'turn/start') return event.data.turn
+  }
+  return undefined
+}
+
+/**
+ * Phase-specific status glyph, keyed by the running step's active timing bucket.
+ * `ttft` is the pre-first-token wait a running turn falls back to between steps.
+ */
+export const TIMING_BUCKET_GLYPHS: Record<TimingBucket, string> = {
+  ttft: '◍',
+  thinking: '✻',
+  responding: '●',
+  tools: '⚙',
+}
+
+/**
+ * Derive the currently open step's active timing bucket, or `undefined` when no
+ * step is open. The open step is the last `step/start` with no later matching
+ * `step/end`; its bucket is replayed with the same rules as {@link stepTimingAt}.
+ * @param events - Session events to scan.
+ * @returns The open step's active bucket, or `undefined`.
+ */
+export function openStepPhase(events: readonly SessionEvent[]): TimingBucket | undefined {
+  let startIndex = -1
+  let start: Extract<SessionEvent, { type: 'step/start' }> | undefined
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index] as SessionEvent
+    if (event.type === 'step/end') return undefined
+    if (event.type === 'step/start') {
+      startIndex = index
+      start = event
+      break
+    }
+    if (event.type === 'turn/end') return undefined
+  }
+  if (start === undefined) return undefined
+  const position = start.data
+  const state = timingState(start.time)
+  for (let index = startIndex + 1; index < events.length; index += 1) {
+    const event = events[index] as SessionEvent
+    if ((event.type === 'assistant/chunk' || event.type === 'tool/call' || event.type === 'step/end')
+      && sameStep(event, position)) {
+      advanceStepTiming(state, event)
+    }
+  }
+  return state.active?.bucket
+}
+
+/**
+ * The running agent's phase glyph, or `undefined` when idle. A running turn
+ * with no open step falls back to the pre-first-token wait so a glyph is always
+ * available while the agent works; it fades in on turn start, throbs while the
+ * turn runs, and fades out on turn end (see {@link fadeGlyph}).
+ * @param events - Session events to derive the phase from.
+ * @param running - Whether the agent is currently running.
+ * @returns The phase glyph, or `undefined` when idle.
+ */
+export function runningPhaseGlyph(events: readonly SessionEvent[], running: boolean): string | undefined {
+  if (!running) return undefined
+  const bucket = openStepPhase(events) ?? 'ttft'
+  return TIMING_BUCKET_GLYPHS[bucket]
+}
+
+/**
+ * The running throb's brightness at continuous clock `nowMs`: a cosine between
+ * {@link STATUS_PULSE_FLOOR} and 1 over {@link STATUS_PULSE_PERIOD_MS}, so the
+ * dim glyph breathes without ever blinking off. Multiplied by the fade envelope
+ * to gate appear/disappear.
+ *
+ * @param nowMs - Monotonic render clock in milliseconds.
+ * @returns Brightness fraction in [{@link STATUS_PULSE_FLOOR}, 1].
+ */
+export function pulseLevel(nowMs: number): number {
+  const phase = (nowMs % STATUS_PULSE_PERIOD_MS) / STATUS_PULSE_PERIOD_MS
+  const wave = 0.5 - 0.5 * Math.cos(2 * Math.PI * phase)
+  return STATUS_PULSE_FLOOR + (1 - STATUS_PULSE_FLOOR) * wave
+}
+
+/**
+ * One frame of the running glyph at fade `opacity` (0 = invisible trough,
+ * 1 = settled dim gray). The character and its width never change — only the
+ * gray fades — so the prompt caret column stays fixed and the glyph reads as
+ * the caret dimly appearing and disappearing, never a colored indicator.
+ *
+ * With truecolor the glyph's 24-bit gray foreground interpolates between
+ * {@link STATUS_FADE_GRAY}'s trough and settled stops, so both the fade and the
+ * running throb render as brightness; below {@link STATUS_FADE_MIN_OPACITY} it
+ * is hidden entirely so the pulse trough disappears. Without truecolor there is
+ * no per-frame gray, so `visible` (driven by the fade envelope, not the opacity)
+ * shows the glyph in the palette's muted role or leaves a blank column — a
+ * single dim appear/disappear at fixed width, still dim rather than accent, and
+ * no throb-driven blink. With color off entirely a visible glyph is bare,
+ * holding the caret column on a monochrome terminal.
+ *
+ * @param glyph - The phase glyph to paint.
+ * @param palette - Active palette supplying the muted (dim gray) role.
+ * @param colorEnabled - Whether ANSI is emitted at all.
+ * @param truecolor - Whether the terminal accepts 24-bit foreground codes.
+ * @param opacity - Brightness fraction in [0, 1] for the truecolor gray.
+ * @param visible - Whether the non-truecolor fallback shows the glyph at all.
+ * @returns The dim-gray glyph at this opacity, or a single space when hidden.
+ */
+export function fadeGlyph(
+  glyph: string,
+  palette: Palette,
+  colorEnabled: boolean,
+  truecolor: boolean,
+  opacity: number,
+  visible: boolean,
+): string {
+  if (truecolor && colorEnabled) {
+    const o = Math.min(Math.max(opacity, 0), 1)
+    // Below the visibility threshold the glyph is fully hidden, so the pulse
+    // trough disappears rather than lingering as a near-background gray.
+    if (o < STATUS_FADE_MIN_OPACITY) return ' '
+    const [tr, tg, tb] = STATUS_FADE_GRAY.trough
+    const [sr, sg, sb] = STATUS_FADE_GRAY.settled
+    const r = Math.round(tr + (sr - tr) * o)
+    const g = Math.round(tg + (sg - tg) * o)
+    const b = Math.round(tb + (sb - tb) * o)
+    return `\x1b[38;2;${r};${g};${b}m${glyph}\x1b[39m`
+  }
+  if (!visible) return ' '
+  return colorEnabled ? palette.muted(glyph) : glyph
+}
+
+/**
+ * Format a non-negative elapsed span at 100 ms resolution.
+ * @param elapsedMs - Elapsed milliseconds.
+ * @returns The formatted duration (e.g. `1.5s`, `2m03.4s`).
+ */
+export function formatStatusDuration(elapsedMs: number): string {
+  const tenths = Math.floor(Math.max(0, elapsedMs) / 100)
+  const seconds = tenths / 10
+  if (seconds < 60) return `${seconds.toFixed(1)}s`
+  const minutes = Math.floor(seconds / 60)
+  return `${minutes}m${(seconds - minutes * 60).toFixed(1).padStart(4, '0')}s`
+}
+
+/**
+ * Format the non-zero timing buckets of one step as a middot-joined summary.
+ * @param totals - Per-phase totals to format.
+ * @param includeModelWait - Whether to always include the model-wait bucket.
+ * @returns The formatted timing summary.
+ */
+export function formatTimingTotals(totals: TimingTotals, includeModelWait = false): string {
+  return TIMING_BUCKETS
+    .filter(bucket => totals[bucket] > 0 || (includeModelWait && bucket === 'ttft'))
+    .map(bucket => `${TIMING_BUCKET_LABELS[bucket]} ${formatStatusDuration(totals[bucket])}`)
+    .join(' · ')
+}
+
+/**
+ * Format the queued-steering badge shown on the running status line.
+ * @param queued - Number of queued steering messages.
+ * @returns The badge text, or `undefined` when nothing is queued.
+ */
+export function formatQueuedStatus(queued: number): string | undefined {
+  return queued > 0 ? `${queued} queued` : undefined
+}
+
+/**
+ * Format a completion timestamp as `YYYY-MM-DD HH:MM:SS` in local time.
+ * @param time - Epoch milliseconds.
+ * @returns The formatted local timestamp.
+ */
+export function formatCompletionTime(time: number): string {
+  const date = new Date(time)
+  const parts = [
+    date.getFullYear().toString().padStart(4, '0'),
+    (date.getMonth() + 1).toString().padStart(2, '0'),
+    date.getDate().toString().padStart(2, '0'),
+  ]
+  const clock = [date.getHours(), date.getMinutes(), date.getSeconds()]
+    .map(value => value.toString().padStart(2, '0'))
+    .join(':')
+  return `${parts.join('-')} ${clock}`
+}

packages/ui/tui/src/session/tokens.ts

@@ -0,0 +1,96 @@
+/**
+ * Running token accounting for the terminal footer. Usage is keyed per
+ * turn/step so replayed or re-emitted usage replaces rather than double-counts.
+ * @module @deepseek-ai/dsh-tui/session/tokens
+ */
+
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+/**
+ * Running token totals for the footer, keyed per turn/step so replayed or
+ * re-emitted usage replaces rather than double-counts; `input` is uncached
+ * input, cache buckets are disjoint.
+ */
+export interface SessionTokenTotals {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  readonly byStep: Map<string, TokenUsage>
+}
+
+/**
+ * Fold one step's usage into the running totals, replacing any prior usage
+ * logged for the same turn/step.
+ * @param totals - Running totals mutated in place.
+ * @param turn - Turn index of the usage.
+ * @param step - Step index of the usage.
+ * @param usage - The step's token usage.
+ */
+export function recordTokenUsage(totals: SessionTokenTotals, turn: number, step: number, usage: TokenUsage): void {
+  const key = `${turn}:${step}`
+  const previous = totals.byStep.get(key)
+  if (previous !== undefined) {
+    totals.input -= previous.inputTokens
+    totals.output -= previous.outputTokens
+    totals.cacheRead -= previous.cacheReadTokens ?? 0
+    totals.cacheWrite -= previous.cacheWriteTokens ?? 0
+  }
+  totals.byStep.set(key, usage)
+  totals.input += usage.inputTokens
+  totals.output += usage.outputTokens
+  totals.cacheRead += usage.cacheReadTokens ?? 0
+  totals.cacheWrite += usage.cacheWriteTokens ?? 0
+}
+
+/**
+ * Fold a usage-bearing session event into the running totals.
+ * @param totals - Running totals mutated in place.
+ * @param event - Session event; ignored when it carries no usage.
+ */
+export function recordEventUsage(totals: SessionTokenTotals, event: SessionEvent): void {
+  if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+    recordTokenUsage(totals, event.data.turn, event.data.step, event.data.chunk.usage)
+  } else if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+    recordTokenUsage(totals, event.data.turn, event.data.step, event.data.usage)
+  }
+}
+
+/**
+ * Share of billed input (prompt) tokens served from the provider cache, as an
+ * integer percent, or `undefined` before any input is billed (avoids 0/0 and a
+ * meaningless rate on an empty session).
+ * @param totals - Running totals to measure.
+ * @returns The cache hit rate percent, or `undefined` when no input is billed.
+ */
+export function cacheHitRate(totals: SessionTokenTotals): number | undefined {
+  const billedInput = totals.input + totals.cacheRead + totals.cacheWrite
+  if (billedInput === 0) return undefined
+  return Math.round((totals.cacheRead / billedInput) * 100)
+}
+
+/**
+ * Fold every usage-bearing event in a session into fresh totals.
+ * @param session - Session whose events supply usage.
+ * @returns The accumulated token totals.
+ */
+export function sessionTokens(session: Session): SessionTokenTotals {
+  const totals: SessionTokenTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, byStep: new Map() }
+  for (const event of session.events) {
+    recordEventUsage(totals, event)
+  }
+  return totals
+}
+
+/**
+ * Format a token count with a compact k/m suffix for the footer.
+ * @param value - Token count.
+ * @returns The compact display string.
+ */
+export 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`
+}

packages/ui/tui/src/skill-invocation.ts

@@ -0,0 +1,67 @@
+/**
+ * Manual `/skill:<name> [instructions]` parsing and model-visible rendering for
+ * the terminal front door.
+ * @module @deepseek-ai/dsh-tui/skill-invocation
+ */
+
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type { SkillDefinition, SkillResourceBase } from '@deepseek-ai/dsh-skill'
+
+/** Prefix that marks an editor submission as a manual skill invocation. */
+export const SKILL_COMMAND_PREFIX = '/skill:'
+
+/** Parsed `/skill:<name> [instructions]` submission; `name` is empty when the prefix carries no name. */
+export interface ParsedSkillCommand {
+  /** Skill name typed after `/skill:`, up to the first space. */
+  name: string
+  /** Trimmed text after the name; empty when none was typed. */
+  instructions: string
+}
+
+/**
+ * Split a `/skill:<name> [instructions]` submission into its name and trailing instructions.
+ * @param text - trimmed submission that starts with {@link SKILL_COMMAND_PREFIX}.
+ * @returns the skill name and any trailing instructions.
+ */
+export function parseSkillCommand(text: string): ParsedSkillCommand {
+  const rest = text.slice(SKILL_COMMAND_PREFIX.length)
+  const spaceIndex = rest.indexOf(' ')
+  if (spaceIndex === -1) return { name: rest, instructions: '' }
+  return { name: rest.slice(0, spaceIndex), instructions: rest.slice(spaceIndex + 1).trim() }
+}
+
+/** Model-visible line locating a manually invoked skill's relative resources, or `undefined` when the provider has no base. */
+function skillResourceReference(base: SkillResourceBase | undefined): string | undefined {
+  if (base === undefined) return undefined
+  switch (base.kind) {
+    case 'directory':
+      return `References in this skill are relative to ${base.path}.`
+    case 'url':
+      return `References in this skill are relative to ${base.url}.`
+    case 'opaque':
+      return base.description
+    default:
+      return assertNever(base, 'SkillResourceBase.kind')
+  }
+}
+
+/**
+ * Render a manually invoked skill into the model-visible user-message text. The
+ * `<skill>` block carries the body and, when the provider supplies one, its
+ * resource base; the trimmed `instructions` follow the block as the user's
+ * request for this turn. The name is registry-validated kebab-case
+ * (the skill registry rejects any other) and the resource base is trusted
+ * same-process provider prose, so — unlike the model-facing `dsh-tool-skill`
+ * result, which escapes for a tool channel — this user turn is assembled raw.
+ * @param skill - the loaded skill definition.
+ * @param instructions - trimmed text typed after `/skill:<name>`; empty when absent.
+ * @returns the user-message text delivered to the agent.
+ */
+export function renderSkillInvocation(skill: SkillDefinition, instructions: string): string {
+  const lines = [`<skill name="${skill.name}">`]
+  const reference = skillResourceReference(skill.resourceBase)
+  if (reference !== undefined) lines.push(reference, '')
+  lines.push(skill.content, '</skill>')
+  const block = lines.join('\n')
+  return instructions === '' ? block : `${block}\n\n${instructions}`
+}

packages/ui/tui/src/xml-tool-output.ts

@@ -0,0 +1,138 @@
+/** Conservative readable-tree rendering for model-facing text containing one XML document. */
+
+import { SaxesParser } from 'saxes'
+
+interface XmlElement {
+  readonly name: string
+  readonly attributes: readonly XmlAttribute[]
+  readonly children: XmlNode[]
+}
+
+interface XmlAttribute {
+  readonly name: string
+  readonly value: string
+}
+
+type XmlNode = XmlElement | string
+
+function parseXml(source: string, display: (text: string) => string): XmlElement | undefined {
+  const parser = new SaxesParser({ xmlns: false })
+  const stack: XmlElement[] = []
+  let root: XmlElement | undefined
+  const state = { invalid: false }
+  const reject = (): void => { state.invalid = true }
+  parser.on('opentag', (tag) => {
+    const element: XmlElement = {
+      name: tag.name,
+      // Attribute values and text pass through `display` because character references can
+      // expand to valid-XML control characters (tab, CR, DEL, C1) that pre-parse escaping
+      // of the raw source never saw. Element names cannot carry them: control characters
+      // are not XML name characters and character references do not apply inside names.
+      attributes: Object.entries(tag.attributes).map(([name, value]) => ({ name, value: display(value) })),
+      children: [],
+    }
+    const parent = stack.at(-1)
+    if (parent === undefined) {
+      if (root !== undefined) reject()
+      root = element
+    } else {
+      parent.children.push(element)
+    }
+    stack.push(element)
+  })
+  parser.on('text', (text) => {
+    const parent = stack.at(-1)
+    if (parent === undefined) {
+      if (text.trim() !== '') reject()
+    } else {
+      parent.children.push(display(text))
+    }
+  })
+  parser.on('cdata', (text) => {
+    const parent = stack.at(-1)
+    if (parent === undefined) reject()
+    else parent.children.push(display(text))
+  })
+  parser.on('closetag', () => { stack.pop() })
+  parser.on('xmldecl', reject)
+  parser.on('processinginstruction', reject)
+  parser.on('doctype', reject)
+  parser.on('comment', reject)
+  parser.on('error', reject)
+  parser.write(source).close()
+  return state.invalid ? undefined : root
+}
+
+function elementLabel(element: XmlElement): string {
+  const attributes = element.attributes.map(attribute => `${attribute.name}=${JSON.stringify(attribute.value)}`).join(' ')
+  return attributes === '' ? element.name : `${element.name} (${attributes})`
+}
+
+function meaningfulChildren(element: XmlElement): readonly XmlNode[] {
+  return element.children.filter(child => typeof child !== 'string' || child.trim() !== '')
+}
+
+function textBlock(text: string, depth: number): string[] {
+  return text.replace(/^\n|\n$/gu, '').split('\n').map(line => `${'  '.repeat(depth)}${line}`)
+}
+
+function treeLines(element: XmlElement, depth: number, label: (text: string) => string): string[] {
+  const indent = '  '.repeat(depth)
+  const children = meaningfulChildren(element)
+  if (children.length === 0) return [`${indent}${label(elementLabel(element))}`]
+  if (children.length === 1 && typeof children[0] === 'string' && !children[0].includes('\n')) {
+    return [`${indent}${label(`${elementLabel(element)}:`)} ${children[0].trim()}`]
+  }
+  const lines = [`${indent}${label(elementLabel(element))}`]
+  for (const child of children) {
+    if (typeof child === 'string') lines.push(...textBlock(child, depth + 1))
+    else lines.push(...treeLines(child, depth + 1, label))
+  }
+  return lines
+}
+
+function preview(lines: readonly string[], limit: number, omitted: (count: number) => string): string[] {
+  if (lines.length <= limit) return [...lines]
+  const head = Math.ceil(limit / 2)
+  const tail = limit - head
+  return [...lines.slice(0, head), omitted(lines.length - limit), ...lines.slice(lines.length - tail)]
+}
+
+/**
+ * Render a complete XML document as an indented tree, or decline without changing partial/mixed text.
+ * @param source - Raw model-facing text from a context message or unknown tool result.
+ * @param maxChildLines - Collapsed budget independently applied to each top-level child's lines and
+ * to the number of top-level children, so many siblings cannot grow the collapsed card without bound.
+ * @param expanded - Whether to retain every rendered child line.
+ * @param display - Escapes parsed text and attribute values for terminal output; character references
+ * can expand to control characters that pre-parse escaping never saw.
+ * @param label - Styles element names and attributes.
+ * @param omitted - Renders the omitted-line marker for a collapsed child or child range.
+ * @returns Tree rows, or `undefined` when `source` is not one supported complete XML document.
+ */
+export function renderUnknownXml(
+  source: string,
+  maxChildLines: number,
+  expanded: boolean,
+  display: (text: string) => string,
+  label: (text: string) => string,
+  omitted: (count: number) => string,
+): string[] | undefined {
+  const root = parseXml(source, display)
+  if (root === undefined) return undefined
+  const blocks = meaningfulChildren(root).map(child =>
+    typeof child === 'string' ? textBlock(child, 1) : treeLines(child, 1, label))
+  const rootLine = label(elementLabel(root))
+  if (expanded) return [rootLine, ...blocks.flat()]
+  const previewed = blocks.map(block => preview(block, maxChildLines, omitted))
+  if (previewed.length <= maxChildLines) return [rootLine, ...previewed.flat()]
+  const head = Math.ceil(maxChildLines / 2)
+  const tail = maxChildLines - head
+  const hidden = blocks.slice(head, blocks.length - tail).reduce((total, block) => total + block.length, 0)
+  return [
+    rootLine,
+    ...previewed.slice(0, head).flat(),
+    omitted(hidden),
+    ...previewed.slice(previewed.length - tail).flat(),
+  ]
+}

packages/ui/tui/tests/extension.spec.ts

@@ -11,12 +11,12 @@ import type {
   TuiOverlayOptions,
   TuiOverlaySession,
   TuiTheme,
-} from '../src/extension.ts'
+} from '../src/extension/types.ts'
 import {
   TuiExtensionServiceImpl,
   TuiOverlayManager,
   type TuiOverlayDriver,
-} from '../src/overlay-manager.ts'
+} from '../src/extension/overlay-manager.ts'
 
 const theme: TuiTheme = Object.freeze({
   text: (value: string) => `text:${value}`,

packages/ui/tui/tests/harness.ts

@@ -17,10 +17,11 @@ import type {
 import CommandService from '@deepseek-ai/dsh-commands'
 import SessionStore, { SessionId, type Session, type SessionHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { createTuiChat, type Config, type TuiRuntime } from '../src/index.ts'
 import { TestSessionQueryService } from './session-query.ts'
+import TuiPromptService from '../src/prompt.ts'
 
 interface FakeAgent extends Agent {
   status: AgentStatus
@@ -43,6 +44,7 @@ export interface TuiHarnessOptions {
   beforeMount?: (session: Session) => void
   cwd?: string | null
   formatCwd?: TuiRuntime['formatCwd']
+  gitBranch?: TuiRuntime['gitBranch']
   /** Fake-agent creation options (`provider`/`model` seed the model selector's initial target). */
   agentOptions?: AgentOptions
   contextWindow?: number
@@ -93,6 +95,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(CommandService)
   await ctx.plugin(UserInteractionService)
+  await ctx.plugin(TuiPromptService)
   const catalog = options.catalog ?? {
     providers: [{ id: 'deepseek', name: 'DeepSeek' }],
     models: [
@@ -106,12 +109,9 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     },
   } as never)
   if (options.configureContext === undefined) {
-    const tools = options.tools ?? {}
-    ctx.provide('tools', {
-      get(name: string) {
-        return tools[name]
-      },
-    } as never)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    for (const tool of Object.values(options.tools ?? {})) ctx.tools.register(tool)
   } else {
     await options.configureContext(ctx)
   }
@@ -219,7 +219,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   const controller = createTuiChat(ctx, Object.assign({
     ...options.omitWelcome === true ? {} : { welcome: 'Coding agent ready.' },
     sessionId,
-    color: false,
+    theme: { color: false },
   }, options.config), {
     terminal,
     exit,
@@ -229,6 +229,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     ...(options.now === undefined ? {} : { now: options.now }),
     ...(options.formatCwd === undefined ? {} : { formatCwd: options.formatCwd }),
     ...(options.handoffResume === undefined ? {} : { handoffResume: options.handoffResume }),
+    gitBranch: options.gitBranch ?? (() => 'tui-staging'),
   })
   return { ctx, session, agent, terminal, exit, controller }
 }

packages/ui/tui/tests/plugin-shape.spec.ts

@@ -21,6 +21,7 @@ describe('dsh-tui plugin export shape', () => {
       'llm',
       'systemPrompt',
       'tokenMeter',
+      'tuiPrompt',
     ])
     expect(unwrapped.Config).toBeDefined()
     expect(typeof unwrapped.apply).toBe('function')