Merge master into codex/jsonl-storage-identity

.agents/notes/implemented/simplification/2026-07-20-retire-readline-front-door.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-retire-readline-front-door.md: 7ebcfdc246bdf6971418609c61acbd4019aa90cb
+2026-07-20-retire-readline-front-door.zh.md: cf4d03594ed3a0cf31bed96eb2133bd37959084a

.agents/notes/implemented/simplification/2026-07-20-retire-readline-front-door.md

@@ -0,0 +1,46 @@
+# Agent Note: Retire the readline front door and the repl-agent example
+
+Status: implemented
+
+English | [中文](2026-07-20-retire-readline-front-door.zh.md)
+
+## Problem
+
+The repo shipped two interactive terminal front doors: the line-oriented readline channel (`@deepseek-ai/dsh-stdio`) and the full-screen [`@deepseek-ai/dsh-tui`](../feature/2026-07-17-dedicated-full-screen-tui-front-door.md). After the TUI landed, readline's interactive role was redundant — `demo:tui` superseded `demo:repl` as the coding-agent experience — while its remaining real role, pipes and automation, was already served better by the one-shot `@deepseek-ai/dsh-cli-demo` app (task in, DSH-native `text`/`json`/`stream-json` out, durable persistence, signal handling).
+
+The duplication was structural, not just cosmetic: `dsh-stdio-demo` carried a `TerminalMode` (`auto`/`readline`/`tui`) selection seam, ~1,000 lines of readline unit tests, a readline transcript grammar (`[tool call] …` lines) that the CI demo smoke and two built-bin e2es grepped, and an inverted example composition where the flagship `tui-agent` leaf was defined as an include-patch over the `repl-agent` leaf it superseded.
+
+## Decision
+
+Delete the readline front door and the repl-agent example; keep exactly three front-door archetypes: **interactive TUI** (TTY-only, fails loud on pipes), **one-shot CLI** (`-p`/positional task, pipes and automation), and **servers** (ACP / JSON-RPC).
+
+- `packages/ui/stdio` and `examples/repl-agent` are gone. `packages/examples/stdio-demo` is renamed `@deepseek-ai/dsh-tui-demo` (`packages/examples/tui-demo`) and always mounts `dsh-tui`; the `TerminalMode`/`resolveTerminalMode`/`ui.mode` seam is deleted. The bin refuses non-TTY streams **before booting the Loader** (a compose-time throw inside a Loader tree is logged per-entry, not rethrown, so a piped launch would otherwise settle into an idle UI-less process instead of exiting nonzero).
+- `examples/tui-agent/cordis.yml` now owns the coding composition inline (the include-patch inversion is gone); its Code Mode overlay includes its own base. `examples/cordis-agent` moved to the TUI app.
+- `examples/echo-agent` moved to the one-shot `dsh-cli-demo` app; `dsh-cli-demo` gained `-p/--prompt` as the flag form of the single task (mutually exclusive with the positional).
+- The UI-independent with-key coding e2es (`full-loop`, `coding-task`, `resume`, `compaction`, `todo-write`, `code-mode` and their shared harness) moved verbatim from `examples/repl-agent/tests/` to `examples/tui-agent/tests/` — they assemble the stack programmatically and never touched a UI.
+- The SDK wizard's `stdio` run interface became `tui` (`RunInterface = 'acp' | 'tui' | 'embed'`), contributing a `dsh-tui` entry instead of `dsh-stdio`; the generated `index.ts` guards TTY before `startSDK` for the same pre-boot fail-loud reason as the tui-demo bin.
+
+### Testing policy: PTY only for the TUI
+
+Pipes remain the default test medium. PTY-driven subprocess tests are sanctioned **only** where the subject is the TUI itself: `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` (which gained the Code Mode overlay boot scenario, replacing repl-agent's pipe smoke as the overlay's keyless composition proof) and the minimal PTY boot smoke in `examples/cordis-agent` (whose front door IS the TUI). Everything else moved to pipes over the one-shot bin:
+
+- `examples/echo-agent/tests/echo.e2e.ts` proves the Loader boot + mock-model tool round-trip through `stream-json` records instead of readline transcript lines.
+- The CI demo-smoke gate (`scripts/run-gates.ts`, AGENTS.md) runs `demo:echo --output-format stream-json -p "echo ci smoke"` and parses the records structurally.
+- `packages/examples/tui-demo/tests/built-bin.e2e.ts` proves the built bin's piped-launch refusal (nonzero exit + pointer at `dsh-cli-demo`); the echo-round-trip-under-plain-Node and missing-config fail-loud proofs live in `cli-demo`'s built-bin suite.
+- `packages/context/time-context/tests/time-context.e2e.ts` runs one one-shot turn; multi-turn elapsed rendering stays unit-covered in its spec.
+
+## Accepted losses
+
+- **Piped multi-turn in one process** — the readline channel could script several turns over stdin; the one-shot bin runs one task per process. Multi-turn continuity is covered by `RESUME_SESSION_ID`/resume e2es and the TUI's scripted PTY conversation.
+- **Non-TTY `ask_user_question`** — the readline provider was the only non-TTY terminal implementation of `ctx.userInteraction`. A headless run whose model calls `ask_user_question` now fails that tool call (no provider); the ACP bridge remains the non-terminal provider. A future headless deployment that needs it composes its own provider.
+
+## Alternatives considered
+
+- **Keep `dsh-stdio` as a pipe/automation channel without the repl demo** — rejected: its automation role duplicated `dsh-cli-demo` with a weaker contract (unstructured transcript, EOF-exit heuristics vs. one durable turn ending and format-pure output).
+- **Rewrite the piped smokes as PTY drivers** — rejected: PTY is the flakier, more complex medium and is reserved for the one surface pipes cannot prove (real TTY takeover/restore).
+
+## Consequences
+
+- One interactive front door (TUI), one automation front door (one-shot CLI), two servers; no mode-selection seam in the terminal app.
+- ~1,000 lines of readline unit tests deleted with their behavior; the readline transcript grammar is gone from all gates.
+- This supersedes the packaging half of [fold the stdio UI helper](2026-07-04-fold-stdio-ui-helper.md) (the folded package is now deleted) and amends the composition described in [the TUI front-door note](../feature/2026-07-17-dedicated-full-screen-tui-front-door.md) (no `auto` selection; `tui-agent` owns the coding composition).

.agents/notes/implemented/simplification/2026-07-20-retire-readline-front-door.zh.md

@@ -0,0 +1,46 @@
+# Agent Note: 退役 readline 前端与 repl-agent 示例
+
+Status: implemented
+
+[English](2026-07-20-retire-readline-front-door.md) | 中文
+
+## 问题
+
+仓库同时提供两个交互式终端前端：面向行的 readline 通道（`@deepseek-ai/dsh-stdio`）和全屏的 [`@deepseek-ai/dsh-tui`](../feature/2026-07-17-dedicated-full-screen-tui-front-door.md)。TUI 落地之后，readline 的交互角色已经冗余——`demo:tui` 作为编码 agent 体验取代了 `demo:repl`——而它剩下的真实角色（管道与自动化）已由单次任务的 `@deepseek-ai/dsh-cli-demo` 应用以更好的方式承担（任务输入、DSH 原生 `text`/`json`/`stream-json` 输出、持久化、信号处理）。
+
+这种重复是结构性的，不只是表面问题：`dsh-stdio-demo` 携带一个 `TerminalMode`（`auto`/`readline`/`tui`）选择接缝、约 1,000 行 readline 单元测试、一套被 CI 演示冒烟测试和两个 built-bin e2e 用 grep 匹配的 readline 文本记录语法（`[tool call] …` 行），以及一个倒置的示例组合：旗舰 `tui-agent` 叶节点被定义为对它所取代的 `repl-agent` 叶节点的 include patch。
+
+## 决定
+
+删除 readline 前端和 repl-agent 示例；只保留三类前端原型：**交互式 TUI**（仅 TTY，管道下快速失败）、**单次任务 CLI**（`-p`/位置参数任务，服务管道与自动化）以及**服务器**（ACP / JSON-RPC）。
+
+- `packages/ui/stdio` 与 `examples/repl-agent` 已删除。`packages/examples/stdio-demo` 更名为 `@deepseek-ai/dsh-tui-demo`（`packages/examples/tui-demo`）并始终挂载 `dsh-tui`；`TerminalMode`/`resolveTerminalMode`/`ui.mode` 接缝随之删除。bin 在**启动 loader 之前**就拒绝非 TTY 流（Loader 树内组合期抛出的异常按条目记录日志而不会重新抛出，管道启动否则会沉降为一个空闲的无 UI 进程而不是以非零码退出）。
+- `examples/tui-agent/cordis.yml` 现在内联拥有编码组合（include patch 倒置消失）；其 Code Mode 覆盖层 include 自己的基础配置。`examples/cordis-agent` 迁移到 TUI 应用。
+- `examples/echo-agent` 迁移到单次任务的 `dsh-cli-demo` 应用；`dsh-cli-demo` 新增 `-p/--prompt` 作为单个任务的旗标形式（与位置参数互斥）。
+- 与 UI 无关的带密钥编码 e2e（`full-loop`、`coding-task`、`resume`、`compaction`、`todo-write`、`code-mode` 及其共享 harness）原样从 `examples/repl-agent/tests/` 移入 `examples/tui-agent/tests/`——它们以编程方式组装整个栈，从不接触任何 UI。
+- SDK 向导的 `stdio` 运行接口改为 `tui`（`RunInterface = 'acp' | 'tui' | 'embed'`），贡献 `dsh-tui` 配置项而不是 `dsh-stdio`；生成的 `index.ts` 在 `startSDK` 之前检查 TTY，理由与 tui-demo bin 的启动前快速失败相同。
+
+### 测试策略：PTY 仅用于 TUI
+
+管道仍是默认测试介质。PTY 驱动的子进程测试**仅**在被测对象就是 TUI 本身时获准使用：`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts`（新增 Code Mode 覆盖层启动场景，取代 repl-agent 的管道冒烟测试成为该覆盖层的无密钥组合证明）和 `examples/cordis-agent` 中最小的 PTY 启动冒烟测试（其前端就是 TUI）。其余全部改为通过单次任务 bin 走管道：
+
+- `examples/echo-agent/tests/echo.e2e.ts` 通过 `stream-json` 记录证明 Loader 启动 + mock 模型的工具往返，而不是匹配 readline 文本记录行。
+- CI 演示冒烟门禁（`scripts/run-gates.ts`、AGENTS.md）运行 `demo:echo --output-format stream-json -p "echo ci smoke"` 并结构化解析记录。
+- `packages/examples/tui-demo/tests/built-bin.e2e.ts` 证明构建产物 bin 对管道启动的拒绝（非零退出 + 指向 `dsh-cli-demo` 的提示）；纯 Node 下的 echo 往返证明与缺失配置的快速失败证明位于 `cli-demo` 的 built-bin 套件。
+- `packages/context/time-context/tests/time-context.e2e.ts` 运行一个单次任务轮次；多轮 elapsed 渲染仍由其单元测试覆盖。
+
+## 接受的损失
+
+- **单进程内的管道多轮对话**——readline 通道可以通过 stdin 脚本化多个轮次；单次任务 bin 每个进程只运行一个任务。多轮连续性由 `RESUME_SESSION_ID`/resume e2e 和 TUI 的脚本化 PTY 对话覆盖。
+- **非 TTY 的 `ask_user_question`**——readline 提供方是 `ctx.userInteraction` 唯一的非 TTY 终端实现。模型调用 `ask_user_question` 的 headless 运行现在会让该工具调用失败（没有提供方）；ACP 桥接仍是非终端提供方。未来需要它的 headless 部署自行组合提供方。
+
+## 曾考虑的替代方案
+
+- **保留 `dsh-stdio` 作为纯管道/自动化通道而只删 repl 演示**——不予采纳：它的自动化角色以更弱的契约重复了 `dsh-cli-demo`（非结构化文本记录、EOF 退出的启发式判断，对比后者的一次持久轮次结束和格式纯净输出）。
+- **把管道冒烟测试改写为 PTY 驱动**——不予采纳：PTY 是更易波动、更复杂的介质，仅保留给管道无法证明的那一个表面（真实 TTY 的接管/恢复）。
+
+## 后果
+
+- 一个交互式前端（TUI）、一个自动化前端（单次任务 CLI）、两个服务器；终端应用不再有模式选择接缝。
+- 约 1,000 行 readline 单元测试随其行为一起删除；readline 文本记录语法从所有门禁中消失。
+- 本决定取代 [fold the stdio UI helper](2026-07-04-fold-stdio-ui-helper.md) 的打包部分（被折叠的包现已删除），并修订 [TUI 前端 Agent Note](../feature/2026-07-17-dedicated-full-screen-tui-front-door.md) 描述的组合（不再有 `auto` 选择；`tui-agent` 拥有编码组合）。

.agents/notes/implemented/simplification/2026-07-21-tui-remove-cancel-command.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-21-tui-remove-cancel-command.md: f9bad74e7b8f04a162a32e8045d2f874991b9d5d
+2026-07-21-tui-remove-cancel-command.zh.md: 6a4c0af1d2ac345afd775566db21f7a7c0b262da

.agents/notes/implemented/simplification/2026-07-21-tui-remove-cancel-command.md

@@ -0,0 +1,25 @@
+# Agent Note: Drop the TUI `/cancel` slash command
+
+Status: implemented
+
+English | [中文](2026-07-21-tui-remove-cancel-command.zh.md)
+
+## Problem
+
+The TUI exposed two identical ways to cancel a running turn: the `Esc` (and `Ctrl+C`) keybinding and a `/cancel` slash command. Both called `agent.cancel('cancelled from terminal')` with the same reason; when idle, `/cancel` only printed a "The agent is already idle." notice while the keybindings stayed silent. The running status line already advertises the keybinding (`Enter sends steering, Esc cancels`), and cancelling by keystroke needs no editor submission, so the slash command was a second, less discoverable path to the same effect — surface area with no behavior of its own.
+
+## Decision
+
+`/cancel` is removed. Cancelling a running turn is a keybinding-only affordance (`Esc`, or `Ctrl+C` while running), which the status-line hint and the `/help` shortcut list already document. The `baseCommands` autocomplete entry, the `/help` command line, the `case '/cancel'` branch in the editor submit handler, and the "already idle" notice it owned are gone; every other slash command (`/help`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/exit`, `/skill:<name>`) is unchanged. Typing `/cancel` now falls through to the generic `Unknown command:` warning like any other unrecognized slash input.
+
+## Alternatives considered
+
+**Keep `/cancel` as a discoverability alias** — rejected: the running status line and `/help` both name `Esc`, so a typed alias adds a maintained code path and a per-idle-state notice for an action a single keystroke already performs more directly. No consumer needed the editor-submission route to cancellation.
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` asserts `agent.cancelled` contains `'cancelled from terminal'`, driven by the `Esc`/`Ctrl+C` keystrokes in that turn — the sole cancel affordance. The `errors-and-help` and `disposed-terminal` snapshots pin the `/help` line without `/cancel`; per-file coverage on `packages/ui/tui/src` stays at 100%.
+
+## Consequences
+
+There is no way to cancel a turn by editor submission; cancellation is keybinding-only. This is a net removal of a redundant path and its idle-state notice, matching the single-primitive shape the rest of the stop surface already follows ([public stop surface](2026-06-20-public-agent-stop-surface.md)). Restoring a typed cancel would return with the autocomplete entry, the submit-handler branch, and its own test.

.agents/notes/implemented/simplification/2026-07-21-tui-remove-cancel-command.zh.md

@@ -0,0 +1,25 @@
+# Agent Note: Drop the TUI `/cancel` slash command
+
+Status: implemented
+
+[English](2026-07-21-tui-remove-cancel-command.md) | 中文
+
+## Problem
+
+TUI 提供了两条完全相同的取消运行中轮次的方式：`Esc`（以及 `Ctrl+C`）键位绑定，和一条 `/cancel` 斜杠命令。两者都以相同的原因调用 `agent.cancel('cancelled from terminal')`；空闲时 `/cancel` 只打印一条 "The agent is already idle." 通知，而键位绑定保持静默。运行状态行本就标示了该键位绑定（`Enter sends steering, Esc cancels`），且按键取消无需提交编辑器，因此这条斜杠命令只是通往同一效果的第二条、且更难被发现的路径——一块本身不含任何行为的界面。
+
+## Decision
+
+`/cancel` 已移除。取消运行中的轮次是一项仅由键位绑定提供的能力（`Esc`，或运行中的 `Ctrl+C`），状态行提示与 `/help` 快捷键清单已对其作出说明。`baseCommands` 自动补全条目、`/help` 命令行、编辑器提交处理函数中的 `case '/cancel'` 分支，以及它拥有的 "already idle" 通知都已删去；其余每一条斜杠命令（`/help`、`/clear`、`/reasoning`、`/tools`、`/redraw`、`/reload`、`/resume`、`/exit`、`/skill:<name>`）保持不变。键入 `/cancel` 会像任何其他无法识别的斜杠输入一样，落入通用的 `Unknown command:` 警告。
+
+## Alternatives considered
+
+**保留 `/cancel` 作为便于发现的别名。** 否决：运行状态行与 `/help` 都已标示 `Esc`，因此一个键入式别名会为一项单个按键已能更直接完成的操作，增加一条需维护的代码路径和一条逐空闲状态的通知。没有任何消费方需要经由编辑器提交来触发取消。
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` 断言 `agent.cancelled` 包含 `'cancelled from terminal'`，由该轮次中的 `Esc`/`Ctrl+C` 按键驱动——这是唯一的取消能力。`errors-and-help` 与 `disposed-terminal` 快照固定了不含 `/cancel` 的 `/help` 行；`packages/ui/tui/src` 的逐文件覆盖率维持在 100%。
+
+## Consequences
+
+无法再经由编辑器提交取消一个轮次；取消仅由键位绑定提供。这是对一条冗余路径及其空闲状态通知的净移除，与其余停止能力已遵循的单一原语形态一致（[public stop surface](2026-06-20-public-agent-stop-surface.md)）。若要恢复键入式取消，需连同自动补全条目、提交处理函数分支及其专属测试一并回归。

.agents/notes/implemented/simplification/2026-07-21-tui-todo-write-opt-in.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-21-tui-todo-write-opt-in.md: f89f76a462f4d30960254833ab71973f6a4f7655
+2026-07-21-tui-todo-write-opt-in.zh.md: f80d2639612819975f03aea9771019cd5237a2ee

.agents/notes/implemented/simplification/2026-07-21-tui-todo-write-opt-in.md

@@ -0,0 +1,27 @@
+# Agent Note: Ship the TUI without `todo_write`; keep it a one-line opt-in
+
+Status: implemented
+
+English | [中文](2026-07-21-tui-todo-write-opt-in.zh.md)
+
+## Problem
+
+The shipped tui-agent `cordis.yml` loaded `@deepseek-ai/dsh-tool-todo`, exposing `todo_write` by default. The tool is a task-tracking convenience, not a core coding affordance like `bash` or the `read`/`write`/`edit` fs tools; most TUI sessions never call it, yet shipping it enlarges the wire tool list and system prompt for every turn. Meanwhile the TUI's plan rendering is event-driven: `packages/ui/tui/src/index.ts` listens for the `todo/write` session event and `TodoComponent.render` returns nothing when the list is empty, so the front door already tolerates the tool being absent or present with no runtime coupling to the plugin.
+
+## Decision
+
+The tui-agent `cordis.yml` no longer loads `tool-todo`; `todo_write` is opt-in. The `code-mode.cordis.yml` overlay inherits the base composition, so its generated SDK drops `todo_write` too. Enabling it is one entry — add `@deepseek-ai/dsh-tool-todo` to `cordis.yml` (or a `~/.dsh` personal overlay) — after which the model logs the whole-list `todo/write` snapshot and the TUI renders the plan, unchanged. The `TodoItem` type and the `todo/write` event stay in `@deepseek-ai/dsh-session` and the TUI's plan rendering stays wired, so both the default (disabled) and opt-in (enabled) paths are first-class. The sibling acp-agent, headless-agent, and jsonrpc-agent examples still ship the tool.
+
+## Alternatives considered
+
+**Keep `todo_write` in the shipped TUI default** — rejected: it is an opt-in convenience, not a core tool, and shipping it spends every turn's tool-list and prompt budget on a feature most sessions ignore. The examples that still ship it retain the plugin's real-composition coverage.
+
+**Drop the TUI's plan rendering and todo tests along with the default entry** — rejected: the requirement is to support both the enabled and disabled cases, and the event-driven `TodoComponent` already renders plans with zero plugin coupling, so deleting it would discard a working capability for no gain. The enabled path keeps dedicated coverage instead.
+
+## Testing
+
+`examples/tui-agent/tests/tui.snapshot.ts` mounts `ToolTodo` only when a scenario sets `enableTodo`: only the `todo-plan` scenario does (the enabled-path proof, whose `session.jsonl`/`terminal.expected.txt` pin the rendered plan), while every other scenario runs the default todo-free composition. `tests/harness.ts` makes `ToolTodo` a `todo` opt-in that only `tests/todo-write.e2e.ts` sets, so the with-key todo e2e still drives the real tool while the other suites match the shipped stack. The keyless `tests/tui-keyless-smoke.e2e.ts` boots the real `cordis.yml` and asserts nothing about todo, so the default boot is unaffected.
+
+## Consequences
+
+The default TUI wire tool list and system prompt shrink by one tool; a session that wants task tracking adds one plugin entry. `examples/tui-agent/composition.md` (regenerated) and its leaf-entry table no longer list `tool-todo`, and the curated summary in `scripts/gen-doc-graphs.ts` drops it. The `@deepseek-ai/dsh-tool-todo` package is unchanged and still shipped by the acp/headless/jsonrpc examples, so its coverage requirement is met there. Restoring the default would re-add the one `cordis.yml` entry and flip the snapshot/harness opt-in flags back on.

.agents/notes/implemented/simplification/2026-07-21-tui-todo-write-opt-in.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: Ship the TUI without `todo_write`; keep it a one-line opt-in
+
+Status: implemented
+
+[English](2026-07-21-tui-todo-write-opt-in.md) | 中文
+
+## Problem
+
+出厂的 tui-agent `cordis.yml` 加载了 `@deepseek-ai/dsh-tool-todo`，默认向模型暴露 `todo_write`。这个工具是一项任务追踪的便利功能，而非像 `bash` 或 `read`/`write`/`edit` 文件系统工具那样的核心编码能力；多数 TUI 会话从不调用它，但出厂加载它会让每一轮的协议工具列表和系统提示词都随之变大。而 TUI 的计划渲染是事件驱动的：`packages/ui/tui/src/index.ts` 监听 `todo/write` 会话事件，`TodoComponent.render` 在列表为空时不返回任何内容，因此这个入口本就能容忍该工具的缺席或存在，与该插件没有任何运行时耦合。
+
+## Decision
+
+tui-agent `cordis.yml` 不再加载 `tool-todo`；`todo_write` 改为可选启用。`code-mode.cordis.yml` 覆盖配置继承基础组合，因此它生成的 SDK 同样不再包含 `todo_write`。启用它只需一条配置项——把 `@deepseek-ai/dsh-tool-todo` 加入 `cordis.yml`（或 `~/.dsh` 的个人覆盖配置）——此后模型照旧记录整份清单的 `todo/write` 快照，TUI 照旧渲染该计划。`TodoItem` 类型与 `todo/write` 事件仍留在 `@deepseek-ai/dsh-session`，TUI 的计划渲染也保持接线，因此默认（禁用）与可选启用（启用）两条路径都是一等公民。同类的 acp-agent、headless-agent、jsonrpc-agent 示例仍然出厂携带该工具。
+
+## Alternatives considered
+
+**在出厂的 TUI 默认配置中保留 `todo_write`。** 否决：它是一项可选启用的便利功能，而非核心工具，出厂加载它会为多数会话都忽略的功能花掉每一轮的工具列表与提示词预算。仍然携带它的示例保留了该插件的真实组合覆盖。
+
+**连同默认配置项一起删掉 TUI 的计划渲染与 todo 测试。** 否决：需求是同时支持启用与禁用两种情形，而事件驱动的 `TodoComponent` 本就在零插件耦合下渲染计划，删掉它等于白白丢弃一项可用能力。取而代之，启用路径保留专门的覆盖。
+
+## Testing
+
+`examples/tui-agent/tests/tui.snapshot.ts` 根据逐场景的 `enableTodo` 开关决定是否挂载 `ToolTodo`：只有 `todo-plan` 场景挂载它（启用路径的证明，其 `session.jsonl`/`terminal.expected.txt` 固定了渲染出的计划），其余每个场景都运行默认的无 todo 组合。`tests/harness.ts` 把 `ToolTodo` 做成一个 `todo` 可选项，只有 `tests/todo-write.e2e.ts` 会开启它，因此带密钥的 todo e2e 仍然驱动真实工具，而其余套件与出厂技术栈保持一致。无密钥的 `tests/tui-keyless-smoke.e2e.ts` 启动真实的 `cordis.yml`，且不对 todo 作任何断言，因此默认启动不受影响。
+
+## Consequences
+
+默认 TUI 的协议工具列表和系统提示词少了一个工具；想要任务追踪的会话加一条插件配置项即可。`examples/tui-agent/composition.md`（已重新生成）及其叶子条目表不再列出 `tool-todo`，`scripts/gen-doc-graphs.ts` 中人工维护的摘要也去掉了它。`@deepseek-ai/dsh-tool-todo` 包本身没有变动，仍由 acp/headless/jsonrpc 示例出厂携带，因此它的覆盖需求在那里得到满足。若要恢复默认，只需重新加入那一条 `cordis.yml` 配置项，并把快照/harness 的可选开关重新打开。

.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.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-22-plan-specific-collaboration-state.md: 8a7caf9b1150cb6d3ea2c8ed52e42751f30c773c
+2026-07-22-plan-specific-collaboration-state.zh.md: c4d2528cc06a74ce8c152199bc2503daff315dbf

.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md

@@ -0,0 +1,47 @@
+# Agent Note: Collapse named session modes into plan mode
+
+Status: implemented
+
+English | [中文](2026-07-22-plan-specific-collaboration-state.zh.md)
+
+## Problem
+
+The first plan-mode implementation introduced a generic named-mode registry even though the product shipped only `plan`. `ModeConfig.modes`, definition-name validation, `ctx.modes.list()`, retired-definition fallback, and a synthetic `review` mode in tests existed only to support hypothetical future collaboration modes. The production-specific behavior—plan guidance, `/plan`, and `exit_plan_mode`—still lived in the same package, so the generic API did not isolate a reusable mechanism from plan policy.
+
+The word “mode” also spans unrelated domains. Sandbox mode is an enforcing policy owned by `ctx.sandboxPolicy` and logged as `sandbox/mode`; plan mode is a collaboration stance that contributes guidance and a reviewed exit. Treating both as instances of one named-mode abstraction would obscure their independent ownership. ACP's protocol happens to expose a generic mode picker, but that is an adapter vocabulary rather than evidence that the harness needs a generic mode domain.
+
+## Decision
+
+Plan mode owns a plan-specific product package: `@deepseek-ai/dsh-plan-mode` at `packages/plan/plan-mode/`. The durable fact is `plan/mode: { active: boolean }`, folded by `foldPlanMode(events)` with `false` as the empty-log value. `ctx.planMode.get(agent)` returns `{ active, pending? }`, and `set(agent, active)` records the boundary-applied selection. The existing prompt-submit, continuation, retry, append-failure, and disposal fences remain unchanged in meaning.
+
+Configuration is exactly `{ section: string }`. The package registers the fixed `plan:policy` section, `/plan [message]`, and `exit_plan_mode` itself. Bare `/plan` selects the state; a non-empty argument selects it first and then sends the trimmed text through `agent.steer()`, making the text an ordinary logged user message in the affected step. The exit tool remains registered while plan mode is inactive so the request tool catalog stays stable.
+
+ACP keeps its protocol-level `default` and `plan` ids. The bridge maps those two ids to the boolean service, advertises only that fixed pair, rejects every other id at the adapter boundary, and maps committed `plan/mode` events back to `current_mode_update`. The protocol remains generic without forcing genericity into the product domain.
+
+Sandbox mode and approval policy remain separate enforcement axes. Plan mode neither reads nor writes them, and the simplification introduces no shared base type, registry, or preset abstraction across those concepts.
+
+## Deleted surface
+
+- The arbitrary definition map, mode-name regular expression, reserved-name rules, and per-definition command loop.
+- `ModeDefinition`, the resolved definition map, `ctx.modes.list()`, string-valued get/set state, and unknown or retired mode handling.
+- Test-only `review` mode cases and claims that additional modes can be added through configuration.
+- Generic `mode/set` and `mode:policy` names; the plan package now owns `plan/mode` and `plan:policy`.
+
+## Alternatives considered
+
+**Keep a private generic registry and expose only plan today.** Rejected because the unused name/config machinery would still be maintained and tested without a second production consumer. A future collaboration state can establish the right shared seam from two concrete cases.
+
+**Fold sandbox mode into the same service.** Rejected because collaboration guidance and execution confinement have different owners, lifecycle semantics, and consumers. Their shared English noun is not a domain relationship.
+
+**Let ACP own plan state.** Rejected because TUI, resume, fork, prompt assembly, and the exit tool need the same logged fact independently of ACP. ACP owns only the wire projection.
+
+## Verification
+
+- Package tests retain boundary ordering, retry, append-failure, HMR disposal, prompt assembly, stable native and Code Mode schemas, review outcomes, and invariant coverage through the boolean service.
+- Command tests cover bare `/plan`, `/plan <message>`, absence of `/mode` and `/review`, and effect-scoped removal.
+- ACP tests cover fixed advertisement, both ids, unknown-id rejection, optimistic updates, committed exits, and load replay.
+- The keyless TUI scenario enters through `/plan <message>` and proves `plan/mode` precedes the first request header and that the message is logged under plan guidance.
+
+## Consequences
+
+The implementation has one vocabulary for one shipped feature. Adding another collaboration stance is now an explicit design decision instead of a config entry, while ACP clients continue to see their standard mode picker. The migration intentionally rejects old `mode/set` logs and old `modes.plan.section` configuration under the repository's pre-release format policy.

.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md

@@ -0,0 +1,47 @@
+# Agent Note: 将具名会话模式收敛为 plan mode
+
+Status: implemented
+
+[English](2026-07-22-plan-specific-collaboration-state.md) | 中文
+
+## 问题
+
+产品只交付了 `plan`，首个 plan mode 实现却引入了通用的具名模式注册表。`ModeConfig.modes`、定义名称校验、`ctx.modes.list()`、已退役定义的回退逻辑，以及测试中合成的 `review` 模式，都只为支持假想中的未来协作模式而存在。plan 引导、`/plan` 和 `exit_plan_mode` 这些生产专用行为仍位于同一个包（package）内，因此通用 API 并未将可复用机制与 plan 策略隔离开来。
+
+「mode」一词还横跨互不相关的领域。沙箱模式是由 `ctx.sandboxPolicy` 拥有、以 `sandbox/mode` 记录日志的强制执行策略；plan mode 则是一种协作方式，会贡献引导内容和经评审的退出路径。若把两者都视为同一个具名模式抽象的实例，就会掩盖二者各自独立的归属关系。ACP（Agent Client Protocol）协议恰好暴露了通用模式选择器，但这只是适配器词汇，并不能证明 harness 需要通用模式领域。
+
+## 决策
+
+Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/` 的 `@deepseek-ai/dsh-plan-mode`。持久化事实为 `plan/mode: { active: boolean }`，由 `foldPlanMode(events)` 折叠，空日志值为 `false`。`ctx.planMode.get(agent)` 返回 `{ active, pending? }`，`set(agent, active)` 则记录在边界生效的选择。现有的提示词提交、continuation、重试、追加失败和 dispose（资源释放）栅栏在语义上保持不变。
+
+配置严格为 `{ section: string }`。该包自行注册固定的 `plan:policy` 段、`/plan [message]` 和 `exit_plan_mode`。不带参数的 `/plan` 选择该状态；非空参数则先选择该状态，再通过 `agent.steer()` 发送去除首尾空白后的文本，使该文本在受影响的步骤中成为一条记录到日志的普通用户消息。即使 plan mode 未激活，退出工具仍保持注册，以确保请求工具目录稳定。
+
+ACP 保留协议层的 `default` 和 `plan` id。桥接层把这两个 id 映射到布尔服务，只公布这组固定选项，在适配器边界拒绝其他所有 id，并把已提交的 `plan/mode` 事件映射回 `current_mode_update`。协议仍保持通用性，但不会迫使产品领域也采用通用抽象。
+
+沙箱模式与审批策略仍是彼此独立的强制约束轴。Plan mode 既不读取也不写入二者；此次简化也没有为这些概念引入共享基类型、注册表或预设抽象。
+
+## 删除的接口
+
+- 任意定义映射、模式名正则表达式、保留名称规则以及逐定义命令循环。
+- `ModeDefinition`、解析后的定义映射、`ctx.modes.list()`、字符串值的 get/set 状态，以及未知或已退役模式处理。
+- 仅用于测试的 `review` 模式用例，以及可通过配置添加其他模式的表述。
+- 通用的 `mode/set` 与 `mode:policy` 名称；plan 包拥有 `plan/mode` 与 `plan:policy`。
+
+## 考虑过的替代方案
+
+**保留私有的通用注册表，目前只暴露 plan。** 不予采纳，因为没有第二个生产消费方时，仍需维护和测试未使用的名称与配置机制。未来若出现另一种协作状态，可以从两个具体案例出发建立合适的共享 seam。
+
+**将沙箱模式折叠进同一服务。** 不予采纳，因为协作引导与执行约束有不同的归属方、生命周期语义和消费方。二者的英文名称都含「mode」，不代表存在领域关系。
+
+**让 ACP 拥有 plan 状态。** 不予采纳，因为 TUI、恢复、fork、提示词组装和退出工具都需要在 ACP 之外独立使用同一项已记录事实。ACP 只拥有协议投影。
+
+## 验证
+
+- 包测试通过布尔服务继续覆盖边界顺序、重试、追加失败、HMR（热模块替换）资源释放、提示词组装、稳定的原生 schema 与 Code Mode schema、评审结果和不变式。
+- 命令测试覆盖不带参数的 `/plan`、`/plan <message>`、不存在 `/mode` 和 `/review`，以及随 effect 作用域移除。
+- ACP 测试覆盖固定模式列表公布、两个 id、未知 id 拒绝、乐观更新、已提交退出和加载回放。
+- 无密钥 TUI 场景通过 `/plan <message>` 进入，证明 `plan/mode` 先于首个请求头，且消息在 plan 引导下记录到日志。
+
+## 后果
+
+该实现只用一套词汇描述一项已交付功能。若要添加另一种协作方式，必须显式作出设计决策，而不能只增加配置项；ACP 客户端仍可看到标准模式选择器。根据仓库的预发布格式策略，本次迁移有意拒绝旧的 `mode/set` 日志与 `modes.plan.section` 配置。

.agents/notes/implemented/simplification/2026-07-22-tui-titles-from-session-title-service.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-22-tui-titles-from-session-title-service.md: b54b99647230255cf241415f94aa21b2630c44cd
+2026-07-22-tui-titles-from-session-title-service.zh.md: 67cc3332f0694887d5af0d71997d140b74669f46

.agents/notes/implemented/simplification/2026-07-22-tui-titles-from-session-title-service.md

@@ -0,0 +1,25 @@
+# Agent Note: TUI titles come from the session-title service
+
+Status: implemented
+
+English | [中文](2026-07-22-tui-titles-from-session-title-service.zh.md)
+
+## Problem
+
+Two model-title implementations coexisted after the tui-staging line merged onto master. The TUI carried its own `autoTitle` feature: a fire-and-forget `ctx.llm.stream` call after the first user message that set the terminal window title via OSC 0, with a one-shot latch, its own prompt, its own 40-character cap, and its own resume re-derivation ([auto-title Agent Note](../feature/2026-07-21-tui-auto-pane-title.md), [default-on Agent Note](../feature/2026-07-21-tui-auto-title-default-on.md)). Master had meanwhile landed [log-backed session titles](../feature/2026-07-21-log-backed-session-titles.md): a `sessionTitle` capability whose accepted revisions are durable `session/title` events, with a deterministic fallback and optional model providers. The TUI already consumed `session/title` for its header subtitle and window title, so a session could be titled twice by different strategies, and the TUI's process-local title was invisible to every other consumer (ACP, resume listings, forks).
+
+## Decision
+
+The TUI-local generation is removed; the session-title service is the one title source. `TuiConfig.autoTitle`, the latch, the abort controller, the title prompt, and `titleLine` are gone from `dsh-tui`. The terminal rename stays: the TUI folds the latest logged title on mount (`foldSessionTitle`), renders it as the banner subtitle, and sets the terminal window title to `<session title> — <configured title>` on every accepted `session/title` event — including resumed sessions, whose titles now replay from the log instead of being re-generated.
+
+Model-made titles are a composition choice: `examples/tui-agent/cordis.yml` (and the scripted PTY fixture) mount `@deepseek-ai/dsh-session-title-first-message-llm`, which inherits the main request's route and replaces the spine's deterministic fallback with a short model summary. Deployments without the provider keep the fallback title from `dsh-agent-spine-demo`'s bundled `SessionTitleService`.
+
+## Alternatives considered
+
+**Keep both, letting the logged title win.** This was the first merge resolution: auto-title owned the whole window title until a logged `session/title` arrived in suffix form. It preserved behavior but doubled the model calls on every fresh session and left the TUI's title unobservable in the log, violating model-visible ⟺ logged in spirit and splitting the title contract across two owners.
+
+**Port auto-title's prompt and cap into the service as a third provider.** The first-message-llm provider already exists with the same cadence, a reviewed prompt contract, durable request records, and supersession fencing; a second near-identical provider would be pure duplication.
+
+## Consequences
+
+One title pipeline: durable, replayable, visible to every consumer, and fenced against stale completions by the service. The TUI sheds ~90 lines and its `llm`-streaming path. The cost is that a title now requires the provider plugin in the composition for model quality — a leaf choice, not a TUI default — and the terminal title changes shape from the bare model summary to the suffixed `<title> — <product>` form the log-backed path always used. The superseded auto-title Agent Notes carry pointers here.

.agents/notes/implemented/simplification/2026-07-22-tui-titles-from-session-title-service.zh.md

@@ -0,0 +1,25 @@
+# Agent Note: TUI 标题来自 session-title 服务
+
+Status: implemented
+
+[English](2026-07-22-tui-titles-from-session-title-service.md) | 中文
+
+## 问题
+
+tui-staging 分支合入 master 后，两套模型标题实现并存。TUI 自带 `autoTitle` 特性：在首条用户消息后发起一次 fire-and-forget 的 `ctx.llm.stream` 调用，通过 OSC 0 设置终端窗口标题，带有一次性闩锁、自己的提示词、自己的 40 字符截断和自己的恢复重推导（[auto-title Agent Note](../feature/2026-07-21-tui-auto-pane-title.md)、[default-on Agent Note](../feature/2026-07-21-tui-auto-title-default-on.md)）。而 master 已落地[日志承载的会话标题](../feature/2026-07-21-log-backed-session-titles.md)：一个 `sessionTitle` 能力，其被接受的修订是持久的 `session/title` 事件，带确定性回退和可选的模型 provider。TUI 已经消费 `session/title` 作为横幅副标题和窗口标题，于是一个会话可能被两种策略各标题一次，且 TUI 的进程本地标题对其他所有消费者（ACP、恢复列表、fork）不可见。
+
+## 决策
+
+移除 TUI 本地生成；session-title 服务是唯一的标题来源。`TuiConfig.autoTitle`、闩锁、abort controller、标题提示词和 `titleLine` 全部从 `dsh-tui` 删除。终端重命名保留：TUI 在挂载时折叠最新的已记录标题（`foldSessionTitle`），将其渲染为横幅副标题，并在每个被接受的 `session/title` 事件上把终端窗口标题设为 `<会话标题> — <配置标题>` —— 包括恢复的会话，其标题现在从日志回放而不是重新生成。
+
+模型生成的标题是组合选择：`examples/tui-agent/cordis.yml`（以及脚本化 PTY fixture）挂载 `@deepseek-ai/dsh-session-title-first-message-llm`，它继承主请求的确切路由，用简短的模型摘要替换 spine 的确定性回退。未挂载该 provider 的部署保留 `dsh-agent-spine-demo` 内置 `SessionTitleService` 的回退标题。
+
+## 备选方案
+
+**两者并存，已记录标题胜出。** 这是第一版合并决议：auto-title 独占整个窗口标题，直到已记录的 `session/title` 以后缀形式到达。它保留了行为，但每个新会话产生双倍模型调用，且 TUI 的标题在日志中不可观察，实质上违反 model-visible ⟺ logged，并把标题契约拆给两个所有者。
+
+**把 auto-title 的提示词和截断移植为服务的第三个 provider。** first-message-llm provider 已经存在，节奏相同，且有经过评审的提示词契约、持久的请求记录和替换围栏；再造一个近乎相同的 provider 纯属重复。
+
+## 影响
+
+标题管线归一：持久、可回放、对所有消费者可见，并由服务对过期完成设防。TUI 削减约 90 行及其 `llm` 流式路径。代价是模型质量的标题现在需要在组合中挂载 provider 插件 —— 这是叶配置选择，不是 TUI 默认值 —— 且终端标题形状从裸模型摘要变为日志路径一贯使用的 `<标题> — <产品>` 后缀形式。被取代的 auto-title Agent Note 携带指向本文的指针。